Documentation and knowledge sharing
Do the work, document what others will need, then teach or delegate it when that will increase the team's capability. Documentation is part of completing work, not an optional task after it.
Document knowledge when it explains:
- a decision and its important tradeoffs;
- a repeatable process;
- a system rule, exception, or dependency;
- how to operate, support, or recover something; or
- context another person would otherwise have to rediscover.
Write for the next person. Begin with purpose, use plain language, show the shortest safe path, and link to the authoritative source rather than copying volatile details. Use diagrams for relationships and sequences that are hard to understand linearly.
The author remains responsible for accuracy at publication. The page owner is responsible for review, correction, or retirement as the work changes.
Write learning back into the system
A retrospective, incident review, or project lesson is not complete merely because the discussion was recorded. Apply the learning to at least one durable part of the system: a requirement, specification, design rule, automated test, alert, checklist, playbook, training example, or tool.
Record unsuccessful approaches when their context will prevent useful work from being repeated. State what was tried, what evidence changed the decision, and what conditions would justify reconsidering it.
The test
Did this documentation remove uncertainty and make someone else more capable?
Guidance type: Working agreement
Owner: Company