Documentation map
Write seven documents with different jobs
Avoid one giant generated README. Give each reader a short path to a specific decision and link claims to executable or authoritative evidence.
Product contract
Define users, critical journeys, rules and non-goals.
- Reader
- Product and engineering
- Evidence
- Accepted behavior and policy
- Stale when
- A core rule or audience changes
System map
Show components, trust boundaries and external dependencies.
- Reader
- Engineering and security
- Evidence
- Deployed services and data flows
- Stale when
- Authority or communication path changes
Data dictionary
Explain entities, ownership, retention and invariants.
- Reader
- Engineering, analytics and operations
- Evidence
- Schema, policy and lifecycle
- Stale when
- Meaning changes without migration
Local and build guide
Create a clean, reproducible path from checkout to tests.
- Reader
- New maintainer
- Evidence
- Pinned dependencies and commands
- Stale when
- Only the original machine can build
Deployment and rollback
Explain release authority, configuration and recovery.
- Reader
- Operator and release owner
- Evidence
- Pipeline, environments and runbook
- Stale when
- Dashboard clicks replace the documented path
Operational runbooks
Connect alerts and common failures to bounded actions.
- Reader
- On-call and support
- Evidence
- Signals, queries and verified procedure
- Stale when
- Alerts have no current owner
Decision records
Preserve why consequential alternatives were accepted or rejected.
- Reader
- Future reviewers
- Evidence
- Context, decision, trade-offs and date
- Stale when
- Old decision is treated as permanent truth
Operating principle
Link prose to evidence and ownership
Documentation decays when it restates code without explaining purpose or when no workflow notices it has become false. Keep executable details in scripts and configuration; use prose for meaning, boundaries and operational judgment.
Assign an owner and update trigger to each document. During incidents, onboarding and releases, note where the documentation failed to answer a real question and repair that path.
- Prefer short linked documents
- Verify setup from a clean checkout
- Name owners and update triggers
- Archive superseded decisions visibly
Applied example
Documentation example: 900-line generated README
A repository README lists every component and environment variable but does not state which service owns user identity or how production is deployed.
- Volume created an appearance of completeness
- Critical operator decisions remained missing
- Syntax descriptions duplicated code
- No update owner or verification path existed
Plain answers
Questions to resolve before shipping
Should documentation be generated automatically?+
Automation is useful for facts such as APIs or schemas, but human-owned product meaning, trade-offs and procedures still need review.
Where should documentation live?+
Keep change-coupled technical material near the repository and link to controlled operational systems where access, audit or secrets require separation.
How do we prevent stale docs?+
Give each document an owner, update trigger and practical use in onboarding, review, release or incident workflows.