Code documentation, explained without the jargon

It is rarely the thing that gets a project approved, and often the thing that decides how it goes. Here is code documentation without the vocabulary that usually surrounds it.

The question is rarely whether something can be built, but what it costs to keep running afterwards. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

The short version

Document why, since the code already shows what. 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.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. None of that requires a large budget, only a decision and someone to own it.

A README that gets someone running in ten minutes is worth a lot. In practice this is a scheduling problem more than a technical one. Budget a little time for it every quarter and it never becomes a project of its own.

Making it stick

Out-of-date docs are worse than none. 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.

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
• 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

If any of that sounds like a description of your current setup, it is fixable.