Before you invest in code documentation

The version of this that works is simpler than the version most people imagine. Before you spend anything on code documentation, it is worth confirming a few things are already true.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. If it only works because one person remembers to do something, it does not work yet.

Prerequisites

• You can describe the outcome you want in one sentence
• Someone owns it after the work is done
• Document why, since the code already shows what
• You have a way to tell whether it worked

The mistakes we see most

A README that gets someone running in ten minutes is worth a lot. It is worth being explicit about, because assumptions differ quietly. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

Out-of-date docs are worse than none. This is the sort of thing that compounds, quietly, in both directions. Assume whoever inherits this will have half your context and none of your patience.

In practice

The question is rarely whether something can be built, but what it costs to keep running afterwards. Three things worth confirming about code documentation before you move on:

• Someone can say what the current setup is without going to look
• Document why, since the code already shows what — 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.