Documentation Strategy

Standing Mandates

• ALWAYS audit existing docs before recommending new ones — redundant docs are worse than none.
• ALWAYS specify audience and maintenance owner for every doc type recommended.
• NEVER treat all doc types the same — ADRs, runbooks, and onboarding guides serve different readers.
• NEVER recommend creating documentation without a plan for keeping it current.

Documentation Strategy

Good documentation answers the right question for the right person at the right time. Bad documentation is worse than none — it misleads with false confidence.

Documentation Taxonomy

Each document type has a distinct audience, purpose, and update cadence.

Audience-First Approach

Before writing a single word, answer:

1. Who reads this? (new hire? experienced engineer? product manager? external developer?)
2. When do they read it? (first day? 2am during an incident? planning a new feature?)
3. What state are they in? (curious and learning? stressed and time-pressured? skeptical?)
4. What do they need to walk away with? (understanding? a decision? a completed action?)

Audience determines format:

• Stressed on-call engineer → numbered steps, no prose, commands they can copy
• New hire exploring the system → narrative overview, context, links to more detail
• External API consumer → precise parameter specs, examples for every endpoint, error codes

Docs as Code

Where docs live

Rule: docs that must stay in sync with code belong in the repo. Docs that evolve independently of code belong in the wiki.

Keeping docs fresh

• Review docs in PRs: add a step to your PR template — "Did you update relevant docs?"
• Doc owners: each doc has an owner listed in frontmatter or a CODEOWNERS-style file.
• Freshness dates: add last_reviewed: YYYY-MM-DD to long-lived docs. Stale = > 6 months without review.
• Broken link CI check: add a link checker to your CI pipeline for docs repos.

Documentation Debt

Documentation debt accumulates silently. Treat it like technical debt.

Write when:

• A new system, service, or API launches
• An on-call incident reveals a missing runbook
• The same question is asked by 3+ people

Update when:

• A system design decision changes
• A runbook step fails because reality diverged from the doc
• An API changes signature or behavior

Delete when:

• The system it documents no longer exists
• The doc has been superseded and the old version causes confusion
• It's a stub that was never filled in (replace with a "to be written" notice or remove entirely)

The cost of wrong documentation: an engineer follows an outdated runbook during an incident and makes things worse. Stale docs are actively harmful.

Template Set

See references/templates.md for Architecture Overview, Runbook, and Onboarding Guide templates.

Practical Workflow

Starting a documentation project from scratch

1. Audit what exists (even informal). Don't duplicate.
2. Identify the highest-pain gap (most asked question, most recent incident gap, newest service with no docs).
3. Pick one doc type. Write it to the relevant template.
4. Get one reviewer who matches the target audience — not the author.
5. Merge and announce. A doc no one knows exists doesn't help.
6. Add it to the relevant index/README.

Docs in the PR workflow

Add to your team's PR template:

## Documentation
- [ ] No docs changes needed
- [ ] Updated existing doc: [link]
- [ ] Added new doc: [link]

Escalation Paths