A short guide to code documentation

It comes up on almost every project, usually later than it should. Everything we would tell a client about code documentation in the time it takes to drink a coffee.

The question is rarely whether something can be built, but what it costs to keep running afterwards. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

Why it matters

Document why, since the code already shows what. It is worth being explicit about, because assumptions differ quietly. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

The practical version

A README that gets someone running in ten minutes is worth a lot. That sounds obvious written down. It is still the thing most often skipped. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

Common failure modes

Out-of-date docs are worse than none. Where this goes wrong is almost never a lack of knowledge. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

In practice

Most development decisions are really maintenance decisions wearing a different hat. Three things worth confirming about code documentation before you move on:

• Someone can say what the current setup is without going to look
• A README that gets someone running in ten minutes is worth a lot — and you know whether that is true here
• There is a way to tell whether the last change to this helped

If you are not sure where your systems currently stand on this, it takes us about an hour to find out.