> Imagine you're reading through some documentation and you notice a > problem. Maybe a typo, or something out of date, or something that's > confusing that you could explain better. In one scenario there's a "git > clone" link in the sidebar to a repository that contains a bunch of > markdown files. In another scenario there's an HTML rendering generated > from a literate programming project where the prose is intermixed with the > code and requires a specific version of org-mode and the knowledge of how > to "untangle" something in order to render it.
This is a focus on the technology which I'm reluctant to do, mostly because I have strong opinions about it. I will say from experience that any technology that separates code from explanation will fail. If we focus on what information we require and what structure has to be placed on that information so it can be understood THEN we can ask about the technologies and what they support. > Can I ask, quite seriously and not intending any sarcasm, what you mean > by "detracts from what's important"? > > For me, "what's important" is to communicate ideas, designs, and details > from one developer to another so that others can maintain, modify, and > extend what exists. I've already held forth on what I think that implies > so I won't bore you with it. Consider Clojure's primary data structure implementation. It is basically an immutable, log32, red-black tree. For some people that is more than sufficient, especially if they have been working in the code base for years. For others, especially as a developer new to the project, there is a lot to know. Without this information it is very difficult to contribute. A new developer needs an introduction to the IDEA of immutable data structures with a reference to Okasaki's thesis which is online at http://www.cs.cmu.edu/~rwh/theses/okasaki.pdf (a bibliography). A new developer needs to know that the DESIGN of Clojure relies on these immutable data structures so they don't introduce any "quick and efficient" hacks that violate the design. (a Clojure overview) A new developer needs to know WHAT a red-black tree is, WHY it was chosen, and HOW Clojure maps user-visible data structures to them. (the chapter on this particular data structure) A new developer needs to know the IMPLICATIONS of the choice of log32 since it defines the efficiency. (the design constraints section and the algorithmic analysis section) A new developer needs to know HOW to update a log32 immutable red-black tree. (a pseudocode explanation with pictures) A new developer needs to know HOW the log32 red-black tree is implemented. It is not immediately obvious how the 5-bit chunks are mapped into a 32 bit word. If the task was to re-implement it on a 64 bit word they'd have to know the details to understand the code. (the actual code with explanations of the variables) If the new developer's task is to modify the code for a 64 bit architecture they would need a way to find the code (the table of contents) and places where this information is mentioned (an index). All of the places where it is written need to be properly updated. Even if we focus strictly on what a new developer needs to know we end up with something that smells a lot like a book. From the above we see the need for 1) a bibliography 2) a Clojure overview 3) a chapter focus on this data structure 4) sections on design constraints and algorithmic analysis 5) a section of pseudocode with pictures 6) a section with code and details of the actual implementation 7) a table of contents 8) an index And that's only a few dozen lines of the Clojure source code. Now we know what information we require and what structure has to be placed on that information so it can be understood, managed, and kept up to date with the code. NOW let's talk about technologies that support these requirements. We can examine the ideas for possible technologies to properly organize the above information. Do inline comments in source code files work? Does a Javadoc kind of technology work? Does a wiki on an external website work? Do separate markdown files in the directory tree work? Do we create videos to explain code? Do any of these technologies integrate with the normal edit-compile-test code developement cycle? Does changing the code generate an immediate expectation to update the associated words? I would claim that only a technology that is fully integrated into the developer's main line, day-to-day work cycle will ensure that the associated information up to date. Checking in code ought to require a review of the associated information to ensure that it is up to date; essentially the role of an "editor-in-chief" whose job it is to maintain high quality, READABLE, natural language. Our standard needs to be that anyone can read the words and KNOW that the code is correct, complete, efficent, and well integrated with the rest of the design. This isn't really a technology problem. We have the skill to create any technology we want. The problem is social. There needs to be a focus on creating "professional standards". We need to raise the bar of what we expect as world-class professional programmers. Tim Daly -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
