Documentation is part of the system
Treat records, explanations and update notes as working parts of the service rather than the debris left after launch.
If a process depends on knowledge that lives only in one person's head, that person is not a knowledge base. They are a single point of exhaustion.
Write for the next action
Why it matters
Documentation fails when it describes a system without helping somebody use or repair it.
Do this
Begin each section with the decision or task it supports. Put background after the immediate action and link to deeper detail.
Record provenance and status
Why it matters
Readers need to know whether a statement is confirmed, inferred, drafted or unresolved.
Do this
Label the source, review state and date. Keep unknown information visibly unknown instead of replacing it with plausible text.
Keep decisions beside their reasons
Why it matters
A later maintainer can see what exists but not which constraint made it necessary.
Do this
Record the decision, alternatives considered, evidence used and condition that would justify revisiting it.
Design an update route
Why it matters
A document without ownership becomes increasingly confident about the past.
Do this
Name a review trigger, owner and lightweight way to report a problem. Prefer small verified updates to ceremonial annual rewrites.
Test the document with a handover
Why it matters
Comprehension is easier to assume than to observe.
Do this
Ask somebody unfamiliar with the work to complete a safe representative task using the documentation. Record where they had to ask for hidden context.
Failure states to test
- A draft is later reported as an action
- The source link changes without an archive note
- Sensitive details spread through copied examples
- Nobody knows whether the instruction is current