Documentation exists so a new reader can continue responsibly without repeating discovery or inventing a reason for old work.
Minimum durable context
For a material system, policy, or workflow, document:
- Why: the problem, user need, or constraint.
- What: the current behavior, boundary, and status.
- Who: the accountable owner and, for durable choices, the decider.
- How: the stable interface, data flow, operating path, or publication workflow.
- Evidence: tests, measurements, source material, incidents, or observed results supporting the statement.
- When to review: a date, event, dependency change, risk threshold, or superseding decision.
Route information by purpose
| Information | Durable home |
|---|---|
| Company purpose, principles, and responsibility model | Company documentation |
| Stable product status, requirements, interfaces, and architecture | Product documentation |
| A consequential choice and its trade-offs | Decision record |
| Verified work and operating results for a period | Report |
| Time-sensitive legal, vendor, or market facts | Dated source note with a recheck trigger |
| Temporary continuation context | Private handoff or issue, not public company truth |
Raw conversations are not documentation. Extract stable facts and reasons, remove private material, verify claims, and place each result in its proper durable home.
Status language
Use explicit labels such as current, experimental, planned, deprecated, and unavailable. A roadmap is not evidence that a capability exists. A prototype is not a supported product. A policy is not a certification.
Maintenance
Prefer updating the canonical page over adding a conflicting copy. Link to decisions that explain important boundaries. When a major assumption changes, supersede the relevant decision and update product truth in the same change.