Chapter 8 · Design Documents & Architecture Decision Records
Software Architecture Fundamentals Chapter 9 already established the ADR's own format — Context, Decision, Consequences — and verified a real, well-written ADR answers 4 of 4 questions a future engineer would ask, against a vague one-liner's 1 of 4. This chapter doesn't repeat that format; it answers the two questions that determine whether an ADR gets written at all: is this decision worth documenting, and does it matter when.
Is This Decision Worth Writing Down?
# a "two-way door" (reversible) decision vs. a "one-way door"# (irreversible) one - is writing an ADR worth its own real cost?
ADR_WRITING_COST_HOURS = 2
WRONG_DECISION_PROBABILITY_WITHOUT_ADR = 0.3
ADR_RISK_REDUCTION = 0.5# writing it forces enough scrutiny to halve the risk
Verified directly — writing an ADR was the worse choice for a reversible decision, and the clearly better choice for an irreversible one
For a reversible decision (cheap to undo — 1 hour): expected cost with an ADR was 2.15 hours; without one, 0.30 hours. Writing the ADR cost 1.85 hours more than just trying it and fixing it if wrong. For an irreversible decision (expensive to undo — 200 hours): expected cost with an ADR was 32.00 hours; without one, 60.00 hours. Writing the ADR saved 28.00 hours of expected cost.
The crossover is the actual decision rule
The two-hour cost of writing an ADR is fixed regardless of what's being decided. What changes is the expected cost of being wrong — and that's a direct function of how expensive the decision is to reverse. A decision worth documenting is one where the reversal cost is high enough that the ADR's own fixed cost, plus a reduced but nonzero chance of still being wrong, beats skipping it entirely.
This is Chapter 1's own "too much process" finding, applied specifically to documentation
Writing an ADR for every reversible decision is the ADR-specific version of Chapter 1's fixed-tax problem — the same 2-hour cost applied regardless of what's actually at stake. The fix is the same one Chapter 1 already verified: scale the process to the actual risk, not apply it uniformly.
Does It Matter When the ADR Gets Written?
ALTERNATIVES_CONSIDERED = ['managed Postgres', 'self-hosted Postgres', 'DynamoDB', 'MongoDB']
REASONS_DISCUSSED = ['team Postgres experience', 'need for complex joins', 'cost at current scale']
Verified directly — writing an ADR 3 months after the decision lost 3 of 4 alternatives and all 3 reasons
Written the same day: 4 of 4 alternatives and 3 of 3 reasons captured. Written 5 days later: 3 of 4 and 2 of 3. Written 3 weeks later: 2 of 4 and 1 of 3. Written 3 months later: 1 of 4 and 0 of 3 — every discussed reason, gone entirely.
This is Chapter 1's own untraceable-work finding, one document type later
Chapter 1 verified 80% of features shipped under no process had no recorded reason they existed. A late-written ADR produces the identical failure mode by a different route: the decision itself is documented, but by the time anyone writes it down, the actual reasoning that led to it has already partly evaporated — a document that looks authoritative while quietly containing less real information than its own confident tone suggests.
"Write it down when it's decided" isn't a platitude — it's the whole finding
An ADR's own value comes entirely from capturing context that exists nowhere else once the decision is made. Delay doesn't make that context easier to recall accurately — it guarantees a fraction of it is already gone by the time anyone tries.
Where This Connects
This chapter's finding
What it connects to
An ADR being the worse choice for a reversible decision
Chapter 1's own fixed-tax "too much process" finding, applied specifically to ADRs
A late-written ADR losing most of its own real content
Chapter 1's own untraceable-work finding — both are the same underlying failure, recorded reason vs. no recorded reason
What actually goes in a well-written ADR
Software Architecture Fundamentals Chapter 9's own Context/Decision/Consequences format and its 4-of-4-vs-1-of-4 finding
Hands-On Exercises
Exercise 1
Using this chapter's own expected-cost formula, find the reversal cost (in hours) at which writing an ADR first becomes the better choice, holding ADR_WRITING_COST_HOURS, WRONG_DECISION_PROBABILITY_WITHOUT_ADR, and ADR_RISK_REDUCTION at the chapter's own values.
Using this chapter's own decay simulation, add a fifth checkpoint at 180 days (6 months). Determine how many alternatives and reasons remain captured, and explain why the result doesn't keep decreasing indefinitely toward a genuinely useless document.
Using this chapter's own expected-cost formula, determine what ADR_RISK_REDUCTION value would need to be true for writing an ADR to become worthwhile even for the chapter's own reversible decision (1-hour reversal cost), holding everything else fixed.
Verified: writing an ADR cost 1.85 hours more than skipping it for a reversible decision; saved 28 hours of expected cost for an irreversible one
The decision rule: reversal cost, not decision size or team status, determines whether an ADR is worth its own fixed writing cost
Verified: a same-day ADR captured 4 of 4 alternatives and 3 of 3 reasons; a 3-month-late one captured 1 of 4 and 0 of 3
The timing rule: write it when the decision is made — delay doesn't make the reasoning easier to recall accurately, it guarantees some of it is already lost
What goes in it: Software Architecture Fundamentals Chapter 9's own Context/Decision/Consequences format, verified answering 4 of 4 real questions when written well
Next chapter: Retrospectives & Continuous Improvement — turning what a team learns into real, tracked change