# Architecture Definition Documents, ADRs, and Runbooks: What an SA Delivers

*Published 2026-07-22 · Dmitry Shirokov · shirokoff.ca/blog/architecture-definition-documents*

Early in my career I wrote an eighty-page architecture document. It was thorough, correct, and nobody read past page four. Six weeks later two engineers argued about a message broker my document had already settled on page fifty-one — and neither knew it was there. **An architect's deliverable is not a document; it's a decision the team can act on without you in the room.** The document is the carrier; get it wrong (too long, wrong place, wrong reader) and the decision doesn't travel.

## What an SA actually delivers

A small set of documents, each answering one question for one audience, with a defined lifespan. They are not one big document with chapters.

| Artifact | Answers | Reader | Lifespan |
|---|---|---|---|
| **Architecture Definition Document (ADD)** | What are we building, and why this shape? | Stakeholders + team | The project |
| **Reference architecture** | The reusable pattern for this class of problem | Multiple teams | Long |
| **Architecture Decision Record (ADR)** | Why X over Y, and what did it cost? | Engineers, now + in 2 years | Forever (immutable) |
| **Engineering standards** | How we build here, by default | Every engineer, every PR | Long |
| **Runbook** | How to operate + recover in production | On-call, ops | As long as it runs |

Each should be as short as it can be and still do its job, and live where its reader works — ADRs and standards in the repo next to the code, the runbook next to the alert.

## The ADD: thin on purpose

States what you're building, the shape you chose, and why it fits the constraints — then stops. In it: business context and the constraints that actually bind (compliance, latency, skills, cloud), the target architecture at a level you can hold in your head, and a short "why this, not the obvious alternative." Out of it: implementation detail that'll be stale by sprint two, and exhaustive completeness. Test: if a section wouldn't change how the team builds or how a stakeholder decides, it's reference material — link, don't inline. Closer to fifteen pages than eighty.

## Reference architectures

The reusable answer to a class of problem, abstracted from any single project. Value is consistency; the cost is that it's only useful if referenced, which means opinionated and maintained. A reference architecture that covers every case becomes a menu, and a menu isn't a decision. Ship a narrow one that says "for this common case, do exactly this," and name the two situations to deviate.

## ADRs: the cheapest, most valuable thing you'll write

Captures one decision — context, choice, consequences — and is never edited after acceptance; superseded by a new record. Format (Michael Nygard's): Status / Context / Decision / Consequences. Three rules: **one decision per record** (or it can't be cleanly superseded); **immutable** (write ADR-031 "supersedes ADR-017", never edit — a log you can silently rewrite is no log); **write it when you decide, not after** (a retrospective ADR is reverse-engineered fiction). Live in the repo (`docs/adr/0017-*.md`), reviewed in the PR that enacts the decision.

## Engineering standards: adopted, not imposed

The defaults that let a team move without re-deciding the basics. A standard the team helped shape becomes the path of least resistance; one handed down from a board gets routed around. Write them as a **paved road, not a fence** — a template, a linter, a scaffold that already does it right, so the right way is less work than the wrong way. The best governance I've shipped was a project template that arrived with security, observability, and CI wired — faster to accept than to argue with.

## Runbooks: earns its keep at 3 a.m.

Tells on-call how to operate and recover — alerts and what they mean, dashboards, step-by-step for predictable failures. Task-oriented (what to do when *this* fires), tested (an unfollowed runbook is a hypothesis), honest about destructive steps. The SA seeds it from anticipated failure modes; the team that operates it owns and grows it. New failure → new runbook entry, sometimes a new ADR.

## The traps

The eighty-page ADD nobody reads; the retrospective ADR (rationalisation, not decision); standards imposed from above (correct, universally routed around); the runbook that rots; and the deepest — architecture that lives apart from the code, so the docs and system drift and the team stops trusting the docs.

## The SA is on the delivery team, not above it

The documents that guide implementation are written by someone close enough to it to know what actually binds — reviewing PRs, pairing on the hard integration, feeling the consequences of their own decisions. Artifacts live where work lives: ADRs and standards in the repo, the reference architecture as a template you clone, the runbook next to the alert. Keep a hand in the code — the fastest way to write documents the team ignores is to stop being able to build the thing yourself.

## Carry-away

The deliverable is the decision, not the document. Keep the set small, one job each: the ADD orients (thin), the reference architecture makes a good decision reusable, the ADR makes every decision durable (one per record, immutable, at the moment), standards pave the road, the runbook keeps it alive. If you do one thing, write ADRs in the repo as you decide — the cheapest artifact answering the most expensive question.

*Related: [AI Strategy](https://shirokoff.ca/blog/ai-strategy) · [Data Strategy](https://shirokoff.ca/blog/data-strategy) · [Data Contracts](https://shirokoff.ca/blog/data-contracts) · [Architecture Radar](https://shirokoff.ca/architecture-radar)*