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.
Navigating Nuance: Phrasing for Non-Native Speakers
Okay, you’ve got the basic framework down – the ‘we chose X over Y’ statement is a good starting point. But let’s be honest, translating architectural thinking into precise English can be tricky, especially when your native language doesn’t have direct equivalents for technical jargon or the subtle nuances of decision-making in software development. A common challenge isn’t just what you say, but how you say it, particularly when communicating with colleagues who might have a different understanding of formal language and professional phrasing.
Let’s consider a scenario: You’re reviewing a Pull Request for a new microservice designed to handle user authentication. A colleague writes in the PR description: “Implemented OAuth 2.0 flow.” While technically correct, it lacks context and doesn’t fully communicate the reasoning behind this choice. A more polished approach might be, “We implemented the OAuth 2.0 authorization flow using the implicit grant type for improved developer experience, aligning with our strategy of minimizing server-side session management to reduce operational overhead.” See how much richer that is? It immediately communicates why OAuth 2.0 was selected – not just that it was selected – and links it back to a broader organizational goal (reducing operational overhead).
Another frequent hurdle is expressing trade-offs. Saying “We chose X because Y was slower” isn’t inherently bad, but it can sound dismissive of Y’s merits. A better phrasing would be: “While Y offered faster initial processing times, we opted for X to prioritize long-term scalability and maintainability, acknowledging that the performance difference is likely to diminish as our user base grows.” Notice the acknowledgement – a key element in demonstrating thoughtful consideration. It’s about showing you understood both options and made a deliberate choice based on anticipated future needs.
Finally, don’t be afraid of slightly more complex sentence structures when appropriate. Concise language is valuable, but so is clarity. Using phrases like “Considering the potential for…”, “In light of…”, or “To mitigate the risk of…” demonstrates a higher level of analytical thinking and helps to frame your decisions in a way that’s easier for others to understand and accept. Remember, effective communication isn’t just about conveying information; it’s about building trust and demonstrating a deep understanding of the problem at hand.