Improving Wetware

Because technology is never the issue

Improving Documentation

Posted by Pete McBreen 11 Nov 2009 at 07:48

Seen a few useful blogs on documentation recently.

Jacob Kaplan-Moss has a good look at how the Django culture does documentation.

I especially liked this

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.

My take is that it is possible to produce readable and useful documentation using Rdoc or Javadoc, it is just that most projects do no take the time to produce good documentation. In many cases of Rdoc generated documentation all that is there is the signature to the method and a link to that excerpt of the code… not very useful.