How to Explain an Architecture Decision in English
How to write and present Architecture Decision Records (ADRs) in English: structure, trade-off language, 'we chose X over Y because', and decision documentation phrases.
Architecture decisions shape a system for years or decades. When these decisions are undocumented, they become invisible constraints — the team knows they cannot change something but not why. Architecture Decision Records (ADRs) capture the reasoning behind significant technical decisions and make that reasoning available to everyone who works on the system in the future.
Writing a good ADR in English requires specific vocabulary and structures. This guide covers both.
What Is an Architecture Decision Record?
An ADR is a short document that records a significant architectural decision — what was decided, why, and what alternatives were considered. The most widely used format was proposed by Michael Nygard.
A minimal ADR has five sections:
- Title — a short, action-oriented phrase
- Status — Proposed, Accepted, Deprecated, or Superseded
- Context — the situation that led to the decision
- Decision — what was decided
- Consequences — the results, both positive and negative
Writing the Context Section
The Context section explains the problem space. Write it in present tense, describing the situation as it was when the decision was made.
“Our authentication service currently handles session management using JWTs stored in local storage. We are experiencing security concerns related to XSS vulnerabilities and are evaluating alternatives.”
“We are building a new notification system that needs to fan out messages to up to 50,000 users within five seconds. The current synchronous approach is not viable at this scale.”
Useful Context Phrases
- “At the time of this decision…”
- “The system currently…”
- “We are facing a choice between…”
- “The constraints driving this decision are…”
- “This decision was prompted by…”
The Decision Phrase: “We Chose X Over Y Because”
The core of the Decision section is a statement that names the chosen option and explicitly contrasts it with the alternatives. This structure is the most valuable language pattern in ADR writing.
“We chose PostgreSQL over MongoDB because our data has strong relational structure, we need ACID transactions across multiple tables, and our team has more operational experience with PostgreSQL.”
“We chose to implement a message queue using RabbitMQ over Kafka because our message volume does not justify Kafka’s operational complexity, and RabbitMQ’s existing cluster is already available in our infrastructure.”
“We chose server-side rendering over a single-page application because our primary users have low-bandwidth connections, and initial page load performance is more critical than rich interactivity.”
Alternative Phrasings
- “We opted for X rather than Y due to…”
- “After evaluating X, Y, and Z, we decided on X because…”
- “The decision was made to adopt X. Y was considered but rejected because…”
- “X was selected over Y on the basis that…”
Describing Trade-Offs
Every architecture decision involves trade-offs. Good ADRs make these explicit.
“Choosing a microservices architecture gives us independent deployment and technology flexibility, but it introduces network latency, distributed transaction complexity, and a higher operational burden.”
“Using a managed database service reduces operational overhead significantly, but we lose the ability to tune low-level PostgreSQL settings and we accept a degree of vendor lock-in.”
Trade-Off Vocabulary
- “at the cost of” — used to acknowledge a downside
- “in exchange for” — similarly used for trade-offs
- “the downside is that…”
- “this decision sacrifices X in favour of Y”
- “we accept the trade-off that…”
“We accept the trade-off that a monolith is harder to scale horizontally, in exchange for the significantly reduced operational and cognitive complexity.”
Writing the Consequences Section
The Consequences section describes what happens as a result of the decision — both good and bad.
“Positive consequences: deployment complexity is reduced; the team needs fewer specialist skills to operate the system; cross-service transactions are handled natively by the database.
Negative consequences: horizontal scaling of the application layer requires more memory per instance; the codebase will become harder to navigate as it grows; module boundaries must be maintained with discipline.”
Future Implications
“If our message volume grows beyond 100,000 events per hour, we will need to revisit this decision and evaluate Kafka.” “This decision will be reviewed when we begin the internationalisation work planned for Q4 2026.”
Status Changes
ADRs evolve. When a decision is revisited, update the status rather than deleting the old document.
“Status: Superseded by ADR-0047. The original decision to use REST APIs was superseded when we adopted GraphQL for the frontend data layer.”
“Status: Deprecated. This approach was acceptable at the time but is no longer consistent with our security policy introduced in Q2 2025.”
Practical Phrases for ADR Writing
- “This ADR captures the decision to…”
- “The alternatives considered were: (1)… (2)… (3)…”
- “We rejected Option B because…”
- “The key driver of this decision was…”
- “This decision is reversible, but changing it later would require…”
- “We chose X over Y because X better satisfies the constraints of…”
- “The consequences of this decision are accepted as reasonable given the current scale.”
ADRs are one of the highest-value documents a team can maintain. A well-written ADR explains not just what was built, but why — making the system understandable to the engineers who will maintain and extend it for years to come. The language patterns in this guide will help you write ADRs that are clear, honest, and genuinely useful.