This post originated from an RSS feed registered with Python Buzz by Ryan Tomayko. Original Post: Writing good documentation Feed Title: Ryan Tomayko (weblog/python) Feed URL: http://tomayko.com/feed/ Feed Description: Entries classified under Python. Latest Python Buzz Posts Latest Python Buzz Posts by Ryan Tomayko Latest Posts From Ryan Tomayko (weblog/python)

From Jacob Kaplan-Moss’s recent piece on documenting open source projects:

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.

Hate that shit.

You know what I want? Man pages. For everything. Wouldn’t it be cool if you didn’t have to write roff?

# | Discuss