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:
   - **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
2. 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

3. Document the WHY, not the WHAT:
   - ✅ `// Using exponential backoff here — the payment API has strict rate limits (3 req/sec)`
   - ❌ `// 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

7. 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?
8. Runbooks live in `docs/runbooks/`.

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

### Step 4: README Currency

9. README reflects current state (not v1 state).
10. Setup instructions work on a fresh machine.
11. 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](https://github.com/joelparkerhenderson/architecture-decision-record)