Writing Decision Rationale in Design Documents
Practice articulating the "why" behind technical decisions in design documents.
Decision rationale vocabulary
- Comparison: "We chose X over Y because..." — both options named + specific technical reason
- Principle: "This aligns with our principle of..." — name the principle and define it
- Tiebreaker: "The key factor was..." — quantified comparison of the deciding criterion
- Retrospective: "In hindsight..." — limitation + timeline context + superseding ADR link
- Context-dependent: "Given the constraints of..." — specific constraints + "under different constraints, you might..."
Question 0 of 5
Which sentence correctly uses the "We chose X over Y because..." pattern in decision rationale?
"We chose X over Y because..." is the standard decision rationale sentence — it must name both options and give a specific technical reason that connects to the use case.
- Both options named — "PostgreSQL over DynamoDB" — the reader knows the comparison that was made.
- Use-case specificity — "our query patterns require multi-table joins and ad-hoc filtering" — the reason is grounded in the specific requirements, not generic preference.
- Cost of the alternative named — "expensive Global Secondary Indexes in DynamoDB" — makes the trade-off concrete for someone familiar with DynamoDB.
- Benefit of the chosen option — "handles this natively at no additional operational cost" — completes the argument.
Which sentence correctly uses "this aligns with our principle of..." language?
"This aligns with our principle of..." connects a specific decision to a stated engineering principle — it transforms a preference into a defensible position.
- Specific principle named — "preferring operational simplicity" — not just "best practices" or "our standards".
- Principle defined inline — "reducing engineering time spent on infrastructure maintenance in favour of product development" — defines what the principle means in practice, so readers cannot reinterpret it differently.
- Connection explicit — "choosing a managed service over a self-hosted solution aligns with..." — states exactly how the decision implements the principle.
Which sentence correctly uses "the key factor was..." vocabulary in decision rationale?
"The key factor was..." signals the tiebreaker — the single most decisive criterion when other factors were roughly equal.
- "While both options were technically viable" — acknowledges parity on other dimensions. This framing prevents the "key factor" from being seen as dismissive of technical quality.
- Key factor named precisely — "time-to-production" — specific and measurable.
- Quantified comparison — "one sprint vs. minimum three sprints" — the factor is not just stated but demonstrated. The reader can evaluate whether time-to-production was worth the trade-off.
- Breakdown of the three sprints — "infrastructure setup, security hardening, monitoring configuration" — specificity makes the estimate credible.
Which sentence correctly uses "in hindsight" retrospective language in an ADR update?
"In hindsight..." is the correct phrase for retrospective ADR annotations — it acknowledges changed circumstances without blaming the original decision-makers.
- "In hindsight" — signals this is a retrospective observation, not a judgment about the original decision quality. The decision was reasonable given the information available at the time.
- Specific limitation named — "underestimated the complexity of supporting ad-hoc reporting queries that emerged six months later" — identifies the gap between the original assumptions and the eventual requirements.
- Timeline context — "six months later" — explains why the limitation was not foreseen: the requirement did not exist when the decision was made.
- Superseding ADR linked — "superseded by ADR-0047" — creates the audit trail. Future readers can follow the chain of decisions.
Which passage correctly uses "given the constraints of..." trade-off framing in decision rationale?
"Given the constraints of..." frames a decision as context-dependent — it documents the conditions under which the choice is valid.
- Constraints named specifically — "6-week delivery timeline and a team of four engineers" — not just "limited resources". These constraints are auditable: in 18 months, a reviewer can assess whether they still apply.
- Trade-off explicit — "third-party SDK over custom integration" — the reader knows what was given up (control, lower per-transaction fees) and what was gained (speed, reduced risk).
- "Under different constraints" — the most valuable part. This signals: "if your constraints differ, you might reach a different conclusion". It prevents the decision from being treated as universally optimal when it was specifically optimal for these circumstances.
- Alternative conditions named — "longer timeline or dedicated payment infrastructure expertise" — gives future teams a checklist for when to revisit the decision.