| name | documentation |
| description | Document decisions, not just implementations. ADRs for architectural choices, inline docs for non-obvious code, and runbooks for operational knowledge. |
| category | review |
| applies-to | ["claude","gemini","cursor","copilot","any"] |
| version | 1.0.0 |
Overview
Code explains what. Documentation explains why. The most valuable documentation records decisions that aren't obvious from reading the code: why this architecture, why this tradeoff, why not the obvious alternative.
When to Use
- After any significant architectural decision
- Before complex code that future maintainers will question
- When an operational procedure isn't self-evident
- When a non-obvious tradeoff was made
Process
Step 1: Architectural Decision Records (ADRs)
For every significant architectural decision:
- Write an ADR with:
- Context: What was the situation requiring a decision?
- Decision: What was decided?
- Alternatives considered: What else was evaluated and why rejected?
- Consequences: What are the positive and negative consequences?
- Status: Proposed | Accepted | Deprecated | Superseded
- Store ADRs in
docs/decisions/ as numbered markdown files.
Verify: Every significant decision in the last sprint has an ADR.
Step 2: Code-Level Documentation
- Document the WHY, not the WHAT:
- ✅
// Using exponential backoff here — the payment API has strict rate limits (3 req/sec)
- ❌
// Retry the request
- Document non-obvious algorithmic choices.
- Document external constraints (rate limits, API quirks, platform limitations).
- Remove comments that state the obvious — they add noise.
Verify: Every non-obvious code block has a "why" comment.
Step 3: Runbooks
- For every production process that humans execute, write a runbook:
- When is this runbook used?
- What steps to execute?
- What does "done" look like?
- What could go wrong and how to recover?
- Runbooks live in
docs/runbooks/.
Verify: Every on-call alert has a linked runbook.
Step 4: README Currency
- README reflects current state (not v1 state).
- Setup instructions work on a fresh machine.
- Architecture diagram updated after significant changes.
Common Rationalizations (and Rebuttals)
| Excuse | Rebuttal |
|---|
| "The code is self-documenting" | Code says what; documentation says why. Both are needed. |
| "I'll document it later" | The context in your head right now is irreplaceable. Write it now. |
| "Docs go stale" | Outdated docs are better than no docs. Update when you touch the code. |
Verification
References
