Getting started with code documentation
There is no clever trick in this one, just a handful of decisions worth making deliberately. A short on-ramp to code documentation for teams who have not touched it before.
Code gets read far more often than it gets written, and usually by someone with less context than the author had. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.
What it costs to ignore
Document why, since the code already shows what. The reasoning matters more than the rule, because the rule has exceptions. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.
Your first week
- Find out what is already in place
- A README that gets someone running in ten minutes is worth a lot
- Change one thing and measure it
Out-of-date docs are worse than none. It is worth being explicit about, because assumptions differ quietly. If it only works because one person remembers to do something, it does not work yet.
What this looks like day to day
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
- 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
Pick the one that would hurt most if it failed, and start there.