Wed 11 November 2009 | -- (permalink)

Jacob Kaplan-Moss, co-creator of Django and its awesome documentation, has the following to say regarding the use of auto-generated documentation:

It's really tempting to use an auto-documentation tool like Javadoc or RDoc for reference material.

Don't.

Auto-generated documentation is almost worthless. At best it's a slightly improved version of simply browsing through the source, but most of the time it's easier just to read the source than to navigate the bullshit that these autodoc tools produce. About the only thing auto-generated documentation is good for is filling printed pages when contracts dictate delivery of a certain number of pages of documentation. I feel a particularly deep form of rage every time I click on a "documentation" link and see auto-generated documentation.

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

I'll even go further and say that auto-generated documentation is worse than useless: it lets maintainers fool themselves into thinking they have documentation, thus putting off actually writing good reference by hand. If you don't have documentation just admit to it. Maybe a volunteer will offer to write some! But don't lie and give me that auto-documentation crap.

That makes me feel better! I never learn what I'm looking for when I'm taken to some documentation page that just rehashes all the arguments accepted and returned by some function. Real examples in real english please.

That excerpted rant aside, the rest of the post is worth reading for its advice on how to write good documentation.