I admit my title (“I hate RDoc”) was somewhat tongue-in-cheek, but I think my point stands, that in the bad-old-days the “docs” most libraries in the Java world shipped with were like Buildr’s current RDocs – no intro (in english), few or no examples, etc.

I think that part of the problem is that the structured format of inline docs (JavaDoc, RDoc, perldoc, etc) does not lend itself to writing the “human-readable” documentation that really helps users get the heads around the code and into the same space that the developer was in.

IMO this kind of documentation is best written on a blank white sheet – where the developer can practice getting into the user’s headspace first, then bring the user into their space. “This is what I was thinking and this is how to understand and benefit from it…”

Anyway, a few more cents’ worth. ;-)