Tim, I am in full support of the approach to documentation that you describe, for individuals and organizations that feel that it best supports their needs. It's a good approach. I don't favor requiring an entire programming community to follow it. That's too much of an imposition. I do like the idea of more minimal norms for a community. Docstrings are a good start, but I can see the benefits of slightly more systematic norms or tools for (e.g.) docstrings, or references to more information. I think that it's a matter of degree. Minimal norms shouldn't require too much of programmers. It should be pretty obvious to any experienced programmer that such a norm will be worth following, and it should be easy to follow it. Maybe there should also be norms for more elaborate kinds of documentation for those organizations that want more elaborate kinds--that way, there will be some uniformity among such organizations. That might be the best of both worlds: An adequate minimal norm for documentation, with easy-to-use tool support, plus norms and tool support for extensions to the minimal norm.
On Wednesday, April 30, 2014 2:09:04 AM UTC-5, da...@axiom-developer.org wrote: > > > 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.
