ADRs and technical docs: record why, not just what Intermediate
This page maps the cluster: which question each kind of document answers, and which part to read first.
The problem
Section titled “The problem”A new engineer asks: “Why doesn’t the order service publish to Kafka right after commit instead of going through an outbox table?” Nobody can answer. The person who decided has left, and the Slack thread is long gone.
Two familiar outcomes, exactly as Nygard described in 2011:
- Blind acceptance (cargo-culting): keep the outbox, then copy it into services that don’t need it, because “that’s the architecture”.
- Blind reversal (re-litigating): someone “simplifies” back to direct publishing. Three months later, the lost-event incident happens again.
Code answers what. Git log answers when and who. Nothing in the repo answers why, and which options were rejected: that is the job of an ADR.
Document flow and reading order
Section titled “Document flow and reading order”Loading diagram…
In this cluster
Section titled “In this cluster”| Part | Question it answers |
|---|---|
| What is an ADR | What is an ADR, when is it worth writing, Nygard or MADR? |
| Writing good ADRs | What does a good ADR look like, and what happens to the old ADR when you change your mind? |
| Docs beyond ADRs | When to use design docs, Diátaxis, on-call runbooks, C4 diagrams? |
| Keeping docs alive | How to stop docs from rotting; review checklist for ADRs and READMEs |
| Common mistakes | How ADRs, runbooks and READMEs usually go wrong, and what it costs |
Summary: which question, which document
Section titled “Summary: which question, which document”| Reader’s question | Document type | When to write | Where it lives |
|---|---|---|---|
| “Why does the system work this way?” | ADR | As soon as a hard-to-reverse decision is settled | docs/adr/NNNN-*.md in the repo |
| “How should we do it, which option?” | Design doc / RFC | Before a large change, while things are still fuzzy | Repo or the team’s doc tool, linked from the ADR |
| “How do I run this service?” | README (quickstart) | From the first commit | README.md at the repo root |
| “Alert X is firing, what do I do?” | Runbook | In the same PR that adds the alert | docs/runbooks/, linked from the alert |
| “What does this endpoint/event/env var accept?” | Reference | Generated from code when possible | OpenAPI, event schemas, config tables |
| “How do the big blocks connect?” | C4 diagram, levels 1–2 | When adding/removing a service or datastore | docs/architecture.md |
The cluster’s default: everything above lives in the repo and is reviewed in the same PR as the code. The common exception is a design doc that needs wide comments from outside the team.