monkinetic weblog | redmonk.net

Ok, hoping I can wrap up this little rant over Buildr’s RDocs. I just left a comment over on Assaf’s post, Patience, Buildr docs coming up, and I liked the way it came out so I wanted to reproduce it here:

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…”

Structured docs are great for keeping your code and your documentation together and in sync, but that structure doesn’t lend itself to the free-form prose that (IMHO) makes for a good introduction to a topic (or piece of software). While looking for examples of user-friendly documentation, I stumbled across this guide - Creating User-friendly Documentation (go figure!) - that captures some great tips for writing documentation that users will read and learn from:

The basic characteristics of a user-friendly document can be summarised as:

• User focus
• Task orientation
• Ease of use
• Ease of understanding
• Ease of finding information

Most developers (including Assaf from labnotes) would agree that inline docs are not enough to get a user up to speed on a piece of software. But having put in the effort to provide comprehensive, structured inline docs, it can be tempting to leave it at that - then not get back to it as intended.

This is pathetic.

Tim Bray pointed to a new build tool called Buildr. It’s written in Ruby, and provides an easy-to-write DSL for declaring rules. But the only documentation is the rdoc. There are no examples and no “Getting Started” info that I can find in the docs.

Aaah, a Google search finds the introductory blog post, which Tim did point to and which is slightly useful. At least the authors point to some rake files you can learn from. At the very least, the rdoc Readme (which the home page redirects to) should have pointed here.

I know, it’s a beta, it’s brand new and the developers could not wait to put it out there for their friends to oooh and aaah over. But if you really want us to try it out point us to something more than the rdocs (and this means you too, Tim, “Buildr” should link to something actually useful). This reminds me of the bad old days when all Java code just shipped with the JavaDocs and that was “enough”. The API is not the documentation, folks. It’s a useful part of the documentation, but it’s not enough.

It absolutely gets me hot under the collar when I go to read about some new code and all I get is the API doc. Treat us with respect, people. Take the time to give us a good introduction (this was a start at least), an FAQ, a variety of example apps or code samples, and THEN a pointer to the API docs.

Rdoc has its place, but that place is not your project’s home page.

GRUMBLE GRUMBLE