Writing Decision Records
Context, alternatives and consequences, written once and never edited.
5 to work through
-
intermediate
A team writes architecture decision records that nobody reads. What makes an ADR useful, and what should it deliberately not contain?
2 min answer -
intermediate
A team writes decision records that nobody reads and that do not help when the decision is revisited years later. What is missing?
2 min answer -
intermediate
What makes an architecture decision record valuable two years later, and which parts do teams consistently omit?
3 min answer -
intermediate Multiple choice
Which section is missing from most architecture decision records, and why does it matter?
2 min answer -
advanced
What distinguishes a postmortem that changes the system from one that produces a document, and what makes blamelessness a technical practice rather than a cultural nicety?
3 min answer
4 terms in this topic
Decision Narrative
Writing a decision record so that the reasoning survives the author, focusing on the forces and the rejected options rather than the conclusion.
practiceRejected-Option Record
The part of a decision record that captures what was considered and dismissed and on what grounds - the only content that code, diagrams and current-…
practiceRevisit Condition
The stated, checkable circumstance under which an architectural decision should be reconsidered - the field that turns a historical record into a liv…
practiceWriting Decision Records
Recording a decision so the next person understands why — including the options rejected and the conditions that would reverse it.
Neighbouring topics
Architecture Communication
General material on communicating architecture.
Architecture Diagrams
Choosing an audience and refusing to mix levels of abstraction.
C4 Model
Context, container, component and code as four separate diagrams.
Context Diagrams
The system as one box, with its users and external systems.
Sequence Diagrams
Ordered message exchange, and walking the failure of each arrow.
Data-Flow Diagrams
Following the data across trust boundaries rather than the calls.
Deployment Diagrams
What runs where, in which zone, behind which boundary.
Communicating Threat Models
Making risk legible to people who will fund or accept it.
Technical Proposals
A written argument circulated before the decision feels made.
Architecture Reviews
Reviewing early enough to influence rather than to veto.
Presenting to Executives
Decision first, cost, risk, and what happens if we do nothing.
Presenting to Engineers
Mechanism, alternatives rejected, and what you are unsure about.
Explaining Trade-offs
Naming what was given up, and the condition that would change it.
Handling Disagreement
Arguing from consequences, and escalating in the room.
Negotiation
Trading on interests rather than positions, with priced options.
Documentation Practice
Keeping documents close to the code and honest about staleness.
Presentation Skills
Structure, pacing and the slide that carries the decision.
Written Communication
Writing that survives being read without you in the room.
Facilitation
Running a design session that reaches a decision.