documentation

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:

1. Write an ADR with:
2. Context: What was the situation requiring a decision?
3. Decision: What was decided?
4. Alternatives considered: What else was evaluated and why rejected?
5. Consequences: What are the positive and negative consequences?
6. Status: Proposed | Accepted | Deprecated | Superseded
7. 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

1. Document the WHY, not the WHAT:
2. ✅ // Using exponential backoff here — the payment API has strict rate limits (3 req/sec)
3. ❌ // Retry the request
4. Document non-obvious algorithmic choices.
5. Document external constraints (rate limits, API quirks, platform limitations).
6. Remove comments that state the obvious — they add noise.

Verify: Every non-obvious code block has a "why" comment.

Step 3: Runbooks

1. For every production process that humans execute, write a runbook:
2. When is this runbook used?
3. What steps to execute?
4. What does "done" look like?
5. What could go wrong and how to recover?
6. Runbooks live in docs/runbooks/.

Verify: Every on-call alert has a linked runbook.

Step 4: README Currency

1. README reflects current state (not v1 state).
2. Setup instructions work on a fresh machine.
3. 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

References

• [git-workflow skill](../git-workflow/SKILL.md)
• Michael Nygard's ADR template