Slug: structured-docs-v-the-blank-white-sheet Date: 2007-05-09 Title: Structured Docs v. The Blank White Sheet layout: post

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.