blog.izs.me

I’ve used the term “Documentation Driven Development” in conversation a few times over the years, and people usually seem to just get what I’m talking about. It’s like “test driven development”, and every bit as disciplined, but for docs instead of tests. I certainly did not invent this concept, and it’s very simple.

I also don’t think that many folks realize just how serious I am about this. And the repeated truism that bad documentation is the worst thing in open source seems to indicate that it’s not being evangelized enough.

Here’s the process in a nutshell. This is how I usually write JavaScript modules, but it’s also how I approach designing product changes at npm, from small tweaks to entire new product lines.

1. Before anything else, write down what the thing is in README.md. I use markdown, but any portable plain-text format will do. This takes three parts:

   1. The name of the thing.
   2. The 1-sentence description of what the thing is.
   3. If necessary, a few paragraphs describing the thing.
   4. Example code demonstrating how to use the thing.

   Note: the thing doesn’t exist yet. You do this before it exists.

2. Copy the example code into a test file. (Basically just do const t = require('tap') and throw some asserts around it.) For things bigger than a single JavaScript module, you can also copy the various points of the description into user story issues for QA or whatever process you use to verify that the thing you built is actually what the docs say it is.

3. Now you are ready to write the code that does that thing. Whenever it seems like the usage example was wrong, update it. As it becomes more clear what it is and how it works, keep the docs in sync with the code and the tests. The goal is to maintain 100% test coverage and 100% documentation coverage.

4. When you want to make a change to the thing, first update the docs and then write the code and the test. It doesn’t matter if the test comes along with the code or if you write the code and then the test, but the docs should absolutely be written before any implementation or test code.

If you ever find yourself thinking “It’s done, I just need to update the docs”, then you’ve violated this process by even having that thought. Not only is it not done, but you might’ve done the wrong thing.

It’s fine to write some code to try to figure out what the thing should be. But that is experimental scaffolding, and should not be thought of as anything other than useful garbage, like a sketch on a napkin. Maybe it can be turned into something enduring, but that starts with docs.

Writing clear prose about software is an unreasonably effective way to increase productivity by reducing both the frequency and cost of mistakes. Just as with good tests, it helps ensure that your program does what you think it does, and that you’ve thought it all the way through.

This unreasonable effectiveness of writing things down comes from the fact that a human brain’s working memory size is absurdly small. While it seems that we can hold a lot of things in our mind at once, it’s only by constantly swapping to long-term storage and ignoring increasing numbers of trees in order to see the forest. A written document does not have that problem. We can fully off-load significant chunks of thought with hardly any data-loss, allowing us to think slower and more carefully while still covering a huge semantic surface.

I don’t like using inline comments to generate interface documentation, for the simple reason that my sole focus must be on the user mental model when writing docs, and that should lead the creation of the thing. If I’m writing documentation and implementation at the same time (or even in the same format), I’m naturally inclined to create a “nice implementation”, which may or may not be an interface that meshes well with the user’s mental model.

The design of how a thing is used limits the implementations available, and vice versa, so whichever is done first will tend to limit the scope of the other. It can be a bit of extra work wrestling the code to fit into the constraints of a user’s mental model. But it’s work you only have to do once, as opposed to the ongoing slog of handling bugs and issues that result from trying to shape user expectations to fit an implementation.