Chapter 6: Documenting Decisions: ADRs and Communicating Trade-offs to Stakeholders

Why this matters

The companion SDLC book's Chapter 8 covered ADRs in general depth. This chapter's specific contribution: which decisions in an HLD/LLD process actually warrant an ADR, and how to communicate the same underlying trade-off differently depending on whether the audience is a technical reviewer or a non-technical stakeholder — a skill distinct from writing the ADR itself.

Which HLD/LLD decisions warrant an ADR

[SENIOR INSIGHT] Not every design decision needs a formal ADR — directly the companion SDLC book's Chapter 5 "match rigor to stakes" principle, applied specifically to the HLD/LLD decision stream: an ADR is warranted when a decision is hard to reverse and affects multiple components or teams — squarely HLD-level decisions (which database, which service boundaries, synchronous vs. asynchronous communication between major components) far more often than LLD-level ones (a specific class's internal method structure, which is comparatively cheap to change and affects a narrower audience).

Warrants an ADR: "We chose PostgreSQL over MongoDB for the booking
system" (HLD-level, hard to reverse, affects every component that
will ever query this data).

Usually doesn't warrant an ADR: "We named this internal helper method
`calculateProration` instead of `computeProratedAmount`" (LLD-level,
trivially reversible, affects only the immediate component's own code).

Communicating the same trade-off differently by audience

[IN PRACTICE] The underlying trade-off reasoning doesn't change based on audience, but its framing should — a technical reviewer needs the mechanism-level detail to evaluate whether the reasoning is sound; a non-technical stakeholder (a product manager, an executive) needs the business-impact translation to make an informed decision, without needing (or wanting) the mechanism-level detail at all.

## Technical reviewer framing (for an architecture review)
"We're choosing eventual consistency for the room-availability cache,
accepting a small window (under 2 seconds, per our replication lag
estimate) where a room might appear available when it was JUST booked
by another user. We mitigate this by re-validating availability with a
strongly-consistent check at actual booking confirmation time -- so the
cache's staleness affects only what's DISPLAYED as available, never
what's actually BOOKED."

## Non-technical stakeholder framing (for a product/business review)
"To keep the search results page fast even under heavy traffic, there's
a small chance a room shown as available gets booked by someone else
moments before you confirm -- in that rare case, we'll show a clear
'this room was just booked' message at checkout rather than letting a
double-booking happen. This trade-off lets us keep search fast for
everyone, at the cost of an occasional, clearly-communicated
last-second unavailability message for a small number of users."

[SENIOR INSIGHT] Both framings describe the exact same technical decision and trade-off — the difference is entirely in which details are foregrounded (mechanism for the technical reviewer, user/business impact for the stakeholder) and which are omitted (a stakeholder doesn't need "replication lag" as a term; a technical reviewer needs it specifically to evaluate whether the 2-second window is actually acceptable). Producing only the technical framing for a stakeholder audience (or vice versa) is a common, avoidable communication failure — the same underlying content, wrongly packaged for its audience, fails to actually inform the decision either side needs to make.

Common mistakes

1. Writing an ADR for every LLD-level decision, producing so much documentation overhead that the genuinely important, hard-to-reverse HLD-level ADRs get lost in the volume — matching the companion SDLC book's Chapter 12 warning about over-applying formal process.
2. Not writing an ADR for a genuinely significant, hard-to-reverse HLD decision, leaving future engineers to wonder (and possibly incorrectly re-litigate or accidentally reverse) a decision made for good reasons that are no longer visible anywhere.
3. Presenting the same technical-mechanism-heavy framing to a non-technical stakeholder audience, leaving them unable to actually engage with or meaningfully weigh in on a decision that affects their business area.
4. Presenting only a business-impact framing to a technical review audience, leaving reviewers unable to actually evaluate whether the underlying technical reasoning is sound.

Checklist: documenting decisions and communicating trade-offs effectively

1. Write an ADR for decisions that are hard to reverse AND affect multiple components/teams — predominantly HLD-level decisions.
2. Skip formal ADRs for easily-reversible, narrowly-scoped LLD decisions, to avoid diluting the value of the ADRs that genuinely matter.
3. Translate the same underlying trade-off differently for technical versus non-technical audiences — mechanism-level detail for reviewers who need to evaluate soundness; business/user-impact framing for stakeholders who need to make an informed decision without the mechanism-level detail.
4. Prepare both framings in advance of a review that will include both audiences, rather than improvising the translation on the spot.

Discussion / interview questions

1. "How would you decide whether a specific design decision warrants a formal ADR?" Strong answer: Ask whether the decision is hard to reverse and affects multiple components or teams — HLD-level decisions (database choice, service boundaries) usually qualify; LLD-level decisions (internal method naming) usually don't, since they're comparatively cheap to change and narrowly scoped.

2. "How would you explain a technical trade-off (like choosing eventual consistency for a specific feature) differently to a technical architecture review versus a non-technical product stakeholder?" Strong answer: For the technical review, describe the mechanism (replication lag, the specific staleness window, the mitigation at confirmation time) so reviewers can evaluate soundness; for the stakeholder, translate to user/business impact (occasional last-second unavailability message, in exchange for consistently fast search) without the mechanism-level jargon.

3. "What's the risk of writing a formal ADR for every single design decision, no matter how small?" Strong answer: Documentation volume dilutes the value of the genuinely important, hard-to-reverse ADRs — future readers have to wade through many low-stakes decisions to find the ones that actually matter, undermining the entire point of maintaining ADRs as a curated, high-signal record.

4. "Why might presenting only a technical framing to a non-technical stakeholder audience fail to actually inform their decision?" Strong answer: A stakeholder without the technical background can't meaningfully evaluate mechanism-level detail (replication lag, consistency models) — they need the same trade-off translated into business/user impact terms to actually understand what they're being asked to weigh in on or approve.

Chapter summary / cheat sheet

• ADRs are warranted for decisions that are hard to reverse AND affect multiple components/teams — predominantly HLD-level, rarely LLD-level.
• The underlying trade-off doesn't change by audience, but its framing should: mechanism-level detail for technical reviewers, business/user-impact translation for non-technical stakeholders.
• Over-applying formal ADR documentation to every decision dilutes the value of the genuinely important ones — match rigor to actual stakes, per the companion SDLC book's Chapter 5 principle.
• Prepare both technical and stakeholder framings in advance for any review spanning both audiences, rather than improvising the translation on the spot.

---