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.