Early in my career I wrote an eighty-page architecture document. It had everything — context diagrams, sequence diagrams, a technology matrix, a risk register. It was thorough, it was correct, and I am fairly sure nobody on the delivery team read past page four. Six weeks later two engineers were arguing about which message broker to use, an argument my document had already settled on page fifty-one, and neither of them knew it was in there.
That was the lesson. 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 just the carrier. Get the carrier wrong — too long, in the wrong place, written for the wrong reader — and the decision doesn't travel. This piece is about the document set a solution architect actually owns on a delivery team, and how to write each one so it guides the implementation instead of decorating a wiki. I'll be opinionated, because most of what goes wrong here is a matter of taste that nobody tells you.
What does a solution architect actually deliver?
An SA on a delivery team delivers a small set of documents, each answering one question for one audience, with a defined lifespan. That framing is the whole discipline. The documents are not interchangeable and they are not one big document with chapters — they answer different questions, are read by different people, and live for different lengths of time. Treat them as one artifact and you get the eighty-page brick.
| Artifact | Answers | Primary reader | Lifespan |
|---|---|---|---|
| Architecture Definition Document (ADD) | What are we building, and why this shape? | Stakeholders + the whole team | The project; revised as it evolves |
| Reference architecture | What's the reusable pattern for this class of problem? | Multiple teams, future projects | Long — outlives any one project |
| Architecture Decision Record (ADR) | Why did we decide X over Y, and what did it cost? | Engineers, now and in two years | Forever — immutable, superseded not edited |
| Engineering standards | How do we build things here, by default? | Every engineer, every PR | Long; versioned with the codebase |
| Runbook | How do we operate and recover this in production? | On-call, ops, support | As long as the system runs |
The through-line I hold to: each of these should be as short as it can be and still do its job, and each should live where its reader already works — the ADRs and standards in the repo next to the code, the runbook next to the alert that pages someone at 3 a.m. Architecture that lives in a wiki nobody opens is architecture that didn't happen.
graph TD ADD["Architecture Definition Document
the what & why"] --> REF["Reference architecture
the reusable pattern"] ADD --> ADR["ADRs
the decisions + rationale"] REF --> ADR ADR --> STD["Engineering standards
the defaults / guardrails"] STD --> IMPL["Implementation
the delivery team builds"] ADR --> IMPL IMPL --> RUN["Runbooks
operate + recover"] RUN -.->|"what breaks feeds
the next decision"| ADR
The documents as a system, not a stack. Decisions (ADRs) are the hub — the ADD frames them, the reference architecture informs them, standards operationalise them, and the runbook feeds production reality back into the next one. Everything points at implementation, because that's the only place value shows up.
The Architecture Definition Document: thin on purpose
An ADD states what you're building, the shape you chose, and why that shape fits the constraints — and it stops there. It is the orientation document: a new engineer or a stakeholder should read it and understand the system's intent, its major components, its boundaries, and the two or three decisions that define its character. It is not the place for every decision (those are ADRs), every diagram (keep the ones that teach), or every risk (a register can live beside it).
What earns its place in an ADD: the business context and the constraints that actually bind — the compliance regime, the latency budget, the team's existing skills, the cloud you're already on. Then the target architecture at a level a person can hold in their head: components and their responsibilities, the data flows that matter, the trust boundaries. And a short "why this and not the obvious alternative" — because the reader's first question is always "why didn't you just use X," and answering it once, up front, saves ten meetings.
What I keep out: implementation detail that will be stale by sprint two, and exhaustive completeness. The test I apply — if a section wouldn't change how the team builds or how a stakeholder decides, it's reference material, not the ADD. Link to it, don't inline it. A good ADD is closer to fifteen pages than eighty, and the discipline of keeping it thin is what makes it read.
Reference architectures: the pattern, not the project
A reference architecture is the reusable answer to a class of problem — "how we do event-driven ingestion," "the shape of a RAG system here" — abstracted from any single project so the next team starts from a known-good baseline instead of a blank page. It's the artifact that turns one good decision into an organisational default.
The value is consistency, and consistency has a cost worth naming: a reference architecture is only useful if it's actually referenced, which means it has to be maintained, opinionated, and honest about where it doesn't apply. A reference architecture that tries to cover every case becomes a menu, and a menu is not a decision. I'd rather ship a narrow one that says "for this common case, do exactly this" and names the two situations where you should deviate. This is the same instinct behind my Architecture Radar — a scored, opinionated default beats an even-handed survey, because the team needs a place to start, not a reading list.
ADRs: the cheapest, most valuable thing you'll write
An Architecture Decision Record captures one decision — its context, the choice, and its consequences — and is never edited after it's accepted; it's superseded by a new record instead. If you take one thing from this piece, take ADRs. They are a page each, they cost almost nothing to write, and they answer the question that otherwise costs your organisation the most: why is it like this? Two years from now, when someone wants to rip out the message broker, the ADR tells them what it was chosen over, what constraints drove it, and what you knew at the time — so they change it with knowledge instead of re-litigating from zero.
The format that has never let me down is Michael Nygard's, and it's deliberately minimal:
form: ADR-017 — Use Azure Service Bus for inter-service messaging
Status: Accepted (Proposed | Accepted | Superseded by ADR-031)
Context: What forces are at play? The constraints, the requirement,
the thing we're deciding under. Facts, not opinions.
Decision: What we will do. Active voice: "We will use X."
Consequences: What becomes easier, what becomes harder, what we
accept as a cost. The honest part — every decision has a bill.Three rules make ADRs work, and each is a lesson from getting it wrong. One decision per record — the moment an ADR covers two decisions, it can't be cleanly superseded. Immutable — you never edit an accepted ADR; if the decision changes, you write ADR-031 marked "supersedes ADR-017" and set the old one to Superseded, because a decision log you can silently rewrite is indistinguishable from having no log. And write it when you decide, not after — a retrospective ADR is fiction, reverse-engineered rationale for a choice you've forgotten the real reasons for. The whole value is capturing what you knew at the moment of the decision.
They live in the repo — docs/adr/0017-service-bus.md — so they're versioned with the code, reviewed in the PR that implements the decision, and searchable by the people who'll need them. An ADR in Confluence, divorced from the commit that enacted it, is already halfway to stale.
Engineering standards: guardrails the team accepts, not rules imposed
Engineering standards are the defaults — how we name things, structure services, handle errors, secure data, write tests — that let a team move fast without re-deciding the basics on every PR. The distinction that decides whether they work is adopted versus imposed. A standard the team helped shape and can see the reason for becomes the path of least resistance. A standard handed down from an architecture board becomes something to route around, and now you have two problems: the workaround and the resentment.
So I write standards as a paved road, not a fence. The paved road is the easy default — a template, a linter rule, a scaffold that already does it the right way — so doing the right thing is less work than doing the wrong thing. The best "governance" I've shipped wasn't a policy document; it was a project template that arrived with the security controls, the observability, and the CI already wired, so the standard was faster to accept than to argue with. I wrote about that exact pattern for the interface layer in data contracts: the enforcement that survives is the enforcement that's cheaper than the alternative.
Runbooks: the document that earns its keep at 3 a.m.
A runbook tells whoever is on call how to operate the system and recover it when it breaks — the alerts and what they mean, the dashboards, the routine operations, and the step-by-step for the failure modes you can predict. It is the least glamorous artifact and often the one that determines whether a good architecture survives contact with production.
A runbook that works has a specific shape: it's task-oriented (not "here's how the system works" but "here's what to do when this fires"), it's tested (a runbook nobody has followed under pressure is a hypothesis), and it's honest about the destructive steps — the restart that drops in-flight work, the failover that has a data-loss window. The SA usually seeds the runbook from the failure modes the design anticipates, and the team that operates it owns and grows it, because the failures you learn about in production are the ones no design predicted. When something breaks in a way the runbook didn't cover, the fix isn't just the incident — it's the new runbook entry, and sometimes a new ADR.
The failure modes I watch for, each earned. The eighty-page ADD nobody reads — thoroughness mistaken for usefulness. The retrospective ADR — written after the fact, so it records a rationalisation instead of a decision. Standards imposed from above — technically correct, universally routed around. The runbook that rots — accurate at launch, quietly wrong by the third incident because nobody updates it. And the deepest one: architecture that lives apart from the code — decisions in a wiki, standards in a slide deck, the repo evolving without either. When the documents and the system drift apart, the documents lose, and the team stops trusting them entirely.
The SA is on the delivery team, not above it
Everything above rests on one stance: the architect is a member of the delivery team, not a governance function that visits it. The documents that guide implementation are written by someone who is close enough to the implementation to know what actually binds — someone reviewing PRs, pairing on the hard integration, and feeling the consequences of their own decisions. An architecture handed down and walked away from is an architecture that gets quietly renegotiated in code, and then the documents are wrong and nobody says so.
Concretely, that means the artifacts live where the work lives. The ADRs and standards are in the repo. The reference architecture is a template you can clone, not a diagram you admire. The runbook sits next to the alert. And the architect keeps a hand in the code — not to own it, but to stay honest, because the fastest way to write documents the team ignores is to stop being able to build the thing yourself.
graph LR
subgraph Repo["Lives in the repo, versioned with the code"]
A["docs/adr/*.md"]
S["docs/standards/*.md"]
T["templates/ (the paved road)"]
R["runbooks/*.md"]
end
subgraph Elsewhere["Lives where its reader works"]
ADDx["ADD — shared with stakeholders"]
REFx["Reference architecture — the catalog"]
end
A --> PR["Reviewed in the PR that enacts the decision"]
T --> PR
PR --> PROD["Production"]
PROD --> R
R -.->|"new failure mode"| A
Where the documents live is not a filing decision — it's an architecture decision. The artifacts an engineer needs while building sit in the repo and move through code review; the ones a stakeholder needs sit where stakeholders read. Put an engineer's document in a stakeholder's tool and it dies of distance.
What to carry away
The deliverable is never the document — it's the decision the team can act on without you there, and the document is only as good as how far that decision travels. Keep the set small and give each artifact one job: the ADD orients (thin, on purpose), the reference architecture makes a good decision reusable, the ADR makes every decision durable (one per record, immutable, written at the moment), the standards pave the road so the right way is the easy way, and the runbook keeps it alive in production.
If you do only one thing, write ADRs, and write them in the repo as you decide. They are the cheapest artifact and they answer the most expensive question. And write all of it as a member of the team that has to build from it — close enough to feel your own decisions land, because that closeness is the only thing that keeps the documents honest. For the strategy layer above these, see AI strategy and data strategy; for the opinionated defaults these documents point to, the Architecture Radar is where I keep mine.