DevelopersGlobal 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
- ADRs written for significant architectural decisions
- Non-obvious code blocks have "why" comments
- Every production alert has a linked runbook
- README is current and setup instructions work