What to ask your agency about code documentation
There is no clever trick in this one, just a handful of decisions worth making deliberately. If you are briefing an agency or a freelancer on code documentation, these questions are worth asking early.
The question is rarely whether something can be built, but what it costs to keep running afterwards. If it only works because one person remembers to do something, it does not work yet.
Questions worth asking
- Who will actually do this work, and have they done it before?
- How will we know afterwards whether it worked?
- What happens if it needs changing in a year?
- What are you assuming that we have not confirmed?
What a good answer sounds like
Document why, since the code already shows what. The reasoning matters more than the rule, because the rule has exceptions. It is the sort of thing that looks like polish right up until it costs you an enquiry.
Out-of-date docs are worse than none. Getting it slightly wrong is survivable. Ignoring it entirely is not. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.
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
- 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 any of that sounds like a description of your current setup, it is fixable.