Deciding what is worth writing down
Documenting everything is impossible and documenting nothing is expensive. The line is more findable than it looks.
Teams oscillate between documenting nothing and attempting to document everything, which collapses under its own maintenance cost. The useful question is not what could be written down but what will be needed by someone who cannot ask. For broader context on maintaining shared technical documentation, GitHub Docs is a useful reference.
The test: who will need this, and can they ask?
Write it down when the answer would otherwise require interrupting a specific person, and when that person is asleep, on leave, or gone.
That test excludes a great deal — anything that is obvious from the work itself, anything used once, anything that changes weekly — and it includes the things whose absence actually hurts. For a practical software-side reference on the limits of self-reported operational data, this resource adds useful detail.
Anything known by exactly one person is the priority, regardless of how mundane it seems. The obscure deployment step and the reason for an odd configuration are worth more written down than a polished overview.
The categories that repay the effort
- Decisions and their reasoning, which nobody can reconstruct later.
- Anything with a single holder — the deploy process, the vendor relationship, the odd workaround.
- Recurring processes with a checkable sequence: releases, onboarding, month end, incidents.
- Constraints and gotchas — the things that look wrong and are deliberate.
- Where things are: systems, accounts, who owns what.
What is not worth documenting
Anything that duplicates a system of record. Anything volatile enough to be wrong before it is read. Detailed procedures for tasks done twice a year by an expert — a checklist of the steps that are easy to forget serves better than a full narrative.
And anything written to demonstrate that documentation exists rather than because someone will read it. That material is identifiable by the fact that it is never linked from anywhere.
Write the answer where the question is asked
The most reliable signal of what needs documenting is the questions people actually ask. A question asked twice is a documentation gap, and the answer given in chat is a draft.
The habit worth building is small: when answering a question that has been asked before, write the answer in a document and link to it, rather than answering again.
Short beats complete
A page that covers eighty percent and is read is worth more than a comprehensive document that is skimmed. Length actively deters reading, and in documentation being read is the entire purpose.
Where completeness genuinely matters, structure for scanning — headings, short sections, the common case first and the edge cases below.
One place, and say where it is
The most common documentation failure in distributed teams is not missing pages but three locations, none of which is authoritative. Pick one and state it, including where things are not.