From: Bob Calco Date: 2004-02-03T11:00:38+09:00 Subject: Re: Documentation approaches I always felt Knuth's "literate programming" was an interesting idea, even though IMO it would be nearly impossible to implement with modern RAD environments, and takes a special kind of software engineer/literati to remain disciplined enough to use this approach. Put simply, you write an essay of sorts in a sort of markup language like TeX (for which of course Knuth was famous), organizing your code in a fashion suitable more for human reading than code organization, per se. But every line of code is in there, and there is special syntax for referring to more granular code blocks below as you work your essay from high-level design discussions into low-level implementation dissertations. A translator then pulls the code out and compiles (runs) it, while the human readable version is transformed into something more permanent and readable/viewable - i.e., PostScript, html, etc. Sort of the inverse of what JavaDoc and RDoc do, which pull the comments out. As for the special kind of software engineer required to make it work - I suspect there are very few out there who aspire to the Pulitzer when trying to write a script that gets an urgent job done well enough to move on to the next task. Not every interesting programming task is necessarily something a programmer wants to turn into a treatise. More than that: not every programming task is interesting. Alas, code documentation is fanciful. So writing code in a language that is (more or less) self-documenting like Ruby is the only sane way to go... and even that (as this discussion proves) doesn't solve the general problem of good, explanatory documentation - the kind that helps a consumer of code crawl inside the head of the original designer to grasp his/her frame of reference fully. I suspect someone eager to provide that level of documentation can do so simply - the issue is that most developers don't have the urge to do so. Rather, we avoid doing it like the plague. - Bob | -----Original Message----- | From: Charles Comstock [mailto:cc1@cec.wustl.edu] | Sent: Monday, February 02, 2004 8:05 PM | To: ruby-talk ML | Subject: Re: Documentation approaches | | Gavin Sinclair wrote: | | | >>[...] | > | > | >>We definitely more complete docs on lots of things though, that is my | >>main problem with Ruby. There are lots of things I know I can do, | >>without duplicating work, but since I can't find docs on it, it's | >>difficult to do. The push for RDoc is great, but I still have the same | >>complaints about it that I have of Javadoc, it generally doesn't give | >>some sort of example for each function, class in the library. I learn | >>far more from an example of code use that encompasses a wide part of the | >> library then a list of functions I can call in the library. The 2nd is | >> great, but it only works if you know how to use it already. Fix the | >>documentation and I think ruby will certainly spring ahead. | > | > | > I fully agree on all counts. I'll just mention, though, that RDoc | > actually encourages introductory/usage/example documentation, *so long | as | > the developer wants to write it*. For example: | > | | I wasn't really trying to criticise RDoc or even Javadoc as a method of | documentation, I was trying to point out that they are oft misused. | Many times the developer decides against writing examples, and instead | just lightly explains each function. | | I think the problem with class/library documentation in RDoc or Javadoc | style, is that it's harder when you first dive in to get a coherent | picture of how the library interacts. And that's the key component to a | library, knowing what it does and how to do it. Functions tell how to | set and check state, and generally how to start things and whatnot but | it doesn't describe the core philosophy of how the library works. It's | often very difficult to determine that from documentation that focuses | on each function/field, and not on the grand scope of the library. | Unless each function/field shows a good example on how to use it in the | total context of the library. It would be nice to have a tutorial in | each library to get your feet wet, and while it's certainly there in | some, it's missing in lots, or difficult to find. | | There are certainly excellent examples of documentation in this format | which do a good job of describing exactly what I want above, but there | are many examples where it feels like the documentation is a couple | remarks strewn throughout the source. In that case I prolly will get | more from reading the source then looking at the rdoc. | | Sorry, I certainly think it's great that we have what we have, but I | still feel like we can go alot further. | | > * http://extensions.rubyforge.org/ | > | > The *first thing you see* (an important consideration for people looking | > at an RDoc screen for the first time) is a description of the project, | > installation, usage, technical information, links, etc. | > | > * http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/index.html | > | > Here, the first thing you see is a brief description of the 'pathname' | > Ruby standard library. It could use a one-paragraph description and | usage | > example to help the casual browser (person, not software) decide whether | > they're interested. However, the most important thing is the prominent | > "For documentation, see class Pathname [linked]", which contains intro, | > examples, and a method catalogue. | > | | That's the style I like, particularly if the method catalogue shows how | each function is used in an example. | | > RDoc was certainly not a hinderance to creating decent documentation for | > the 'pathname' library! | | Sorry didn't mean to say it was a hinderance, just that perhaps not all | were as diligent in writing documentation for there libraries as they | could be. | | They say a picture is worth a thousand words, well I say a nicely | commented example that illustrates how the library is supposed to | interact is worth the same as all the single function documentation that | can be thrown at me. | | Many thanks to all who have documented, and also to all those who have | written libraries, I guess I just get frustrated when I find a library | that does what I need, but I don't know how to use it. | | Charlie