Skip to content.

Personal tools
You are here: Home » Members » chrism's Home » Documentation is the Differentiator

Documentation is the Differentiator

Documentation quality is becoming the differentiator between project success and failure.

I think the most important thing we can do in the open source world (far more important than releasing new cool software) is to improve the quality of the documentation of existing software. Software without documentation is pretty much useless. Software with bad documentation is slightly better than useless, but still nearing uselessness. Software with some good documentation but which has incomplete documentation is better than useless, but only for some period of time: you can't keep telling yourself "I'll do it later" or outsource the job of documentation to some mythical "community": it's a chicken and egg scenario. Writing documentation is part of your job description as a programmer.

As the general quality of software improves due to widespread use of good software engineering techniques such as unit and integration testing, documentation quality is becoming the differentiator between project success and failure.

The most valuable descriptions of highly technical things:

  • get to the point quickly without endless theory or architectural navel-gazing.
  • start with an example.
  • are written in an informal style.
  • aren't optimized for brevity, nor are they optimized for testability; instead they are optimized for readability and imparting knowledge.
  • can be read more than once; the first time you read one, you may gain different knowledge from it than the fifth time, but you still gain knowledge.
  • aren't thrown over the wall as an afterthought, never to be consulted or changed again, they evolve over time as the software evolves.
  • are complete
  • are written using proper spelling and grammar

Here are some examples:

If you can create documentation of this quality or better, your project has no chance but to succeed on some level, even if your code is terrible.

Note also that I think that a choice between good docs and better software is a false choice. The act of continually writing documentation always makes software better, because if it's hard to explain, it's probably not very good. Complexity becomes clear very quickly when you need to explain it away; it's usually easier to change the software to be less complex than it is to document something complex. It's frighteningly easy to write undocumentable software.

Created by chrism
Last modified 2009-12-25 07:55 PM


I hope this attitude is contagious. Particularly the part about chicken/egg off-loading documentation to "community."


Well, lots of software gets along fine without documentation. As an easy example, consider how many manuals a Mac user has read compared to how many pieces of software he or she is using.

In contrast, something that is pretty much useless without docs would be an IC chip. The test equipment to discover a random chip's behavior is way too expensive, and mistakes in usage will break your chip. Software is pretty rugged by comparison. I don't think I've ever read any docs for dhclient; I just saw one example usage and got everything I need.

But, certain classes of software are obviously getting judged by their docs, which is good for everyone. One class I've noticed is general-purpose javascript libraries such as jquery, prototype, mochikit, etc. These have heavily-overlapping functionality, so I think users might be picking them based on their docs. I've heard good things about dojo, but I stopped using it years ago partly because the docs weren't serving my needs.

I also agree about community doc wikis. Letting users put annotations on published docs might work, but you have to be a pretty major project for the users to produce all your docs. Even then, you probably have a bad design, for the reasons described above. My favorite model is still for users to submit bugs on the docs, and then let the project integrate the notes "officially". (The integration work might be done by a user, since it's open source.)

add the BFG docs to your examples

I think you can add the BFG docs to the list of examples. I see them updated with each release and looking at checkins; half of the commits are documentation updates.