Writing good documentation (part 1)

http://jacobian.org/writing/good-documentation/

by jacobian • 17 years ago

53 7 17 years ago

gr366• 17 years ago

I think the point about auto-generated documentation being near worthless is an important one. A project I'm working on has a requirement that the documentation be auto-generated and available at a URL on the build server, but nobody reads it. The developers read the comments in the code itself, and the checklist people just check to see that it's there.

thwarted• 17 years ago

Agreed, with you and the author of the OP. I find the worst auto-generated documentation to be class hierarchies, which are problematic from the standpoint of trying to learn how to use a library (often because they lack working example code), and also problematic as a reference because the method lists are cluttered up with private and protected methods that you most likely shouldn't be aware of if you're using the public interface to a library, which is the reason you're reading the documentation to begin with. The lack of example code means you don't have a canonical idiom to use for reference and to build on, especially with things

As the author says, the django documentation is pretty strong. I've always thought PHP.net was an awesome documentation site/reference also, it's easy to browse and find stuff, even if the example code is sometimes messy and there's a bunch of wrong information in the 5+ year old comments. On the other hand, PHP decided to take the class hierarchy approach when documenting SPL. Thanks, ArrayIterator is a descendant of Iterator, but which methods do I need to define to actually create one. Both http://php.net/manual/en/book.spl.php and http://www.php.net/~helly/php/ext/spl/ , which has been a reference since before php.net had entries for this stuff, are a nightmare to try to learn from.

makecheck• 17 years ago

It is still possible to benefit from automatic generation even when a document is mostly written by hand.

For example, you can use generators to run embedded example code, to verify that the results are what they should be (both on day one, and two years from now when the API has changed). New users have every reason to believe that the examples actually work, and when they don't, their impression of the technology is soured.

jamesbritt• 17 years ago

"There’s no substitute for documentation written, organized, and edited by hand."

Which, in the case of rdoc and javadoc, are the docs written as comments with the code.

If you assume auto-generated docs are nothing but class and method names, then yes they are weak. But there is real value in having the docs right there with the code; much easier to keep in sync, for example. The thing is, whether inline or in separate files, someone has to feel motivated to write them.

It makes me wonder just how familiar the author is with these particular tools. Linking to an rdoc sourceforge page, for example, tells me the author does not know that rdoc has been part of Ruby's stdlib for a few years now, and may never have even used it.

The big issue here is culture, not tools. Some number of Rubyists boasts of Ruby's eminent testing culture. I wish I would hear the same enthusiasm for a robust documenting culture as well; because all the needed tools exist but aren't sufficient.

Silhouette• 17 years ago

It's interesting that everyone commenting so far has picked up on the auto-documentation issue.

The main value of these tools, IMHO, is in their ability to present a high-level overview of the code and support drilling down to find the relevant parts for the task at hand, not as a substitute for just reading comments in the code once you've found it. In fact, one of the worst aspects of many auto-documentation tools is the way they obfuscate comments that would otherwise have been written in plain text. Seriously, Javadoc, why do I have to write a <p> between each paragraph just so you can lay the comments out properly in HTML?

To improve the scannability of auto-generated documentation, top of my wish list would be an "important" flag you could put on the key types, functions, etc. Existing tools typically have no sense of priority in the way that a human writer would, giving equal weight to the top-level function that implements an important algorithm and each of a dozen trivial utility functions. Then you wind up with dozens of mostly irrelevant details obscuring the few key points of interest.

The other thing I really wish they'd support is much better grouping of related information. If a bunch of functions and types would naturally be of interest at the same time, then they should be listed together or otherwise associated in the documentation. Most auto-documentation tools suck at this, and even those that provide some facilities to do it tend to fall into the obfuscation trap I mentioned earlier.

timf• 17 years ago

> an "important" flag you could put on the key types, functions, etc.

I liked the "start here" pictures here: http://www.gridgain.com/javadoc/index.html

> grouping of related information

I agree -- if the output of this could be made to make sense. I usually end up doing this manually in a tutorial with a bunch of English around it, I'm skeptical that a list of related items, even if carefully picked, would do much good without that hand-held context from "above" the situation.

onewland• 17 years ago

Under Tutorials > Demonstrate how your project “feels.” bullet, the second sentence is:

This means you that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project.

I think it should be:

This means, for your purposes, that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project.

I'd also just strike out the "pretty" there and replace "should show" with "shows". Maybe replace "most of the different areas" with "the most important areas". Be forceful in your writing!

Writing good documentation (part 1)

Related Stories