# Documentation Standards

Documentation discipline that stays current and useful.

## Rules

1. **Document decisions, not implementations.** The code shows how. The docs explain why. "We chose PostgreSQL over MongoDB because our data is relational and we need transactions" — that's useful. "This function returns a string" — the function signature already says that.

2. **README answers three questions.** What is this? How do I run it? How do I test it? If your README doesn't answer these in under 30 seconds, it's not a README — it's a wall.

3. **API docs are generated, not handwritten.** OpenAPI spec, JSDoc, whatever your stack supports. Generated docs stay in sync. Handwritten docs rot.

4. **Architecture Decision Records for every major choice.** ADR format: Context, Decision, Consequences. Short, dated, immutable. You don't delete ADRs — you supersede them.

5. **Comments explain the unexpected.** If the code is surprising, comment why. If the code is obvious, don't comment. `// increment counter` is noise. `// must increment before persisting to avoid race with cleanup job` is signal.

6. **Docs are code.** They're reviewed, versioned, and tested. If a doc says "run `npm test`" and the command is `npm run test`, the doc is broken. Treat it like a bug.

## What This Replaces

Documentation as an afterthought. Docs become a first-class artifact with the same rigor as code.