Code documentation: what to get right first

We end up explaining this on discovery calls often enough that it deserved writing down. If you only fix one thing about code documentation this quarter, make it the first item below.

The question is rarely whether something can be built, but what it costs to keep running afterwards. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

Start here

Document why, since the code already shows what. Where this goes wrong is almost never a lack of knowledge. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Then this

A README that gets someone running in ten minutes is worth a lot. Small and consistent beats large and occasional here. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

Eventually

Out-of-date docs are worse than none. It is worth being explicit about, because assumptions differ quietly. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

What this looks like day to day

Code gets read far more often than it gets written, and usually by someone with less context than the author had. 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

Worth checking on your own setup before it becomes someone else's problem to fix.