monkinetic weblog | redmonk.net

Since 1999, IX Ed.
« Patience
It’s in my head »

Structured Docs v. The Blank White Sheet

May 8th, 2007 by Steve Ivy

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.

tagged:

related by tag:

This entry was posted on Tuesday, May 8th, 2007 at 8:58 am. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

One Response to “Structured Docs v. The Blank White Sheet”

  1. Assaf Arkin (May 8th, 2007 at 11:41 am )

    I think it’s all about the story.

    I use a library called Facets, a huge collection of assorted classes and methods. You pick the ones you need, require and use them. That’s the whole story behind it, and the RDocs work extremly well.

    But Buildr (or Rails or Net::HTTP or DRb) all these have some story behind them. Where do you start? Where do you go from there? What do you look out for? What would and wouldn’t you do? For these, the piecemeal approach of RDoc is not enough. It doesn’t capture the story behind the software. The prose if you will, but the prose is the way you tell the story.

    I tried to be liberal with the RDocs prose in Buildr, make sure if you drop in the middle of RDocs, you’ll know why you got there, where to go next, even pick a tip or two. I wouldn’t be surprised if you can pickup Buildr from reading the RDocs. But it’s disjoint and confusing and all that just stands in the way. It needs a good storyline.

    Probably not a Hollywood blockbuster, though :-)

Leave a Reply

You must be logged in to post a comment.