Why English? | Writing an Architecture Decision Record Through Context, Drivers, Options, Trade-Offs, Decision, Consequences and Status

ORIENTATION

What this guide covers

Current fact check

Checked on 8 November 2026, Google Cloud’s official ADR overview described records that capture key options, driving requirements and design decisions, and recommended preserving changed decisions and their reasons. AWS Prescriptive Guidance recommended ownership, regular review, central storage, change history and keeping superseded ADRs in the decision log.

What this guide does not cover

This article covers one architecture decision record for a durable technical choice. It does not own general decision logs, engineering design rationales, product requirements documents, security exceptions, incident reports, operational runbooks, system diagrams or complete architecture documentation.

Worked example

Every chapter returns to a fictional student-notification service deciding between direct synchronous sending, a managed queue and scheduled batch processing for non-urgent course reminders. It is fictional, low-stakes and educational; it does not report a real school, clinical decision or guaranteed outcome.

Warm up with eduKate’s guides to explaining scientific evidence and asking better questions in class.

CHAPTER 1 OF 16

1. Choose a Decision Worth Recording

Back to contents

Why this move matters

Use an ADR for a durable choice with meaningful consequences, alternatives or future questions.

Capture why the decision exists

Use an ADR for a durable choice with meaningful consequences, alternatives or future questions. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The team records how non-urgent notifications enter processing, not the name of a temporary test file. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Organisations may set their own thresholds for an ADR. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Choose a Decision Worth Recording”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 2 OF 16

2. Give the Record a Stable Identity

Back to contents

Why this move matters

Assign a short title, identifier, date, owners and repository location.

Capture why the decision exists

Assign a short title, identifier, date, owners and repository location. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, ADR-014 is titled Process Non-Urgent Student Notifications Asynchronously. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Identifiers should remain stable even if a title is clarified. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Give the Record a Stable Identity”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 3 OF 16

3. State the Decision Question Precisely

Back to contents

Why this move matters

Write the choice the team must make and the boundary of the answer.

Capture why the decision exists

Write the choice the team must make and the boundary of the answer. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, How should non-urgent reminders be accepted and processed without delaying the student portal? Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

A question may need splitting if it contains several independent choices. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “State the Decision Question Precisely”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 4 OF 16

4. Describe the Current Context

Back to contents

Why this move matters

Explain the system, users, workload and problem using dated evidence.

Capture why the decision exists

Explain the system, users, workload and problem using dated evidence. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The portal currently waits for an external messaging service during the web request, creating variable response time. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Context can become stale and should be dated. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Describe the Current Context”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 5 OF 16

5. List Functional and Quality Drivers

Back to contents

Why this move matters

Name required behaviour and forces such as reliability, security, latency, cost and operability.

Capture why the decision exists

Name required behaviour and forces such as reliability, security, latency, cost and operability. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The service must accept reminders quickly, protect contact data and support delayed retry without duplicate messages. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Drivers may conflict and need prioritisation. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “List Functional and Quality Drivers”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 6 OF 16

6. Separate Constraints From Preferences

Back to contents

Why this move matters

Identify policy, platform and time constraints, then label team preferences honestly.

Capture why the decision exists

Identify policy, platform and time constraints, then label team preferences honestly. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, Approved cloud services and data residency are constraints; familiarity with one queue is a preference. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

A claimed constraint should have an owner or source. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Separate Constraints From Preferences”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 7 OF 16

7. Describe Each Credible Option Fairly

Back to contents

Why this move matters

Give alternatives comparable scope, assumptions and evidence rather than building a straw option.

Capture why the decision exists

Give alternatives comparable scope, assumptions and evidence rather than building a straw option. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, Direct sending, managed queuing and scheduled batches each receive the same concise description. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

An infeasible option may be excluded with a reason. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Describe Each Credible Option Fairly”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 8 OF 16

8. Compare Options on Shared Criteria

Back to contents

Why this move matters

Use the same decision drivers and explain qualitative or quantitative evidence.

Capture why the decision exists

Use the same decision drivers and explain qualitative or quantitative evidence. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The team compares response latency, retry control, duplicate handling, operational burden, cost and privacy exposure. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Scores should not hide uncertain inputs or arbitrary weights. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Compare Options on Shared Criteria”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 9 OF 16

9. State the Decision in One Unambiguous Sentence

Back to contents

Why this move matters

Name the selected option, applicable scope and effective condition.

Capture why the decision exists

Name the selected option, applicable scope and effective condition. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, Use the managed queue for non-urgent reminders created by the portal after the pilot readiness checks pass. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

The decision should not imply approval beyond its authority. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “State the Decision in One Unambiguous Sentence”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 10 OF 16

10. Explain the Rationale Without Repeating the Table

Back to contents

Why this move matters

Connect the decisive drivers to the selected option and rejected trade-offs.

Capture why the decision exists

Connect the decisive drivers to the selected option and rejected trade-offs. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The queue protects portal response time and supports retry while remaining within the team’s operational capability. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Rationale should acknowledge evidence limits. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Explain the Rationale Without Repeating the Table”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 11 OF 16

11. Record Positive and Negative Consequences

Back to contents

Why this move matters

List new capabilities, costs, complexity, risks and work created by the decision.

Capture why the decision exists

List new capabilities, costs, complexity, risks and work created by the decision. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The choice adds durable retry but introduces queue monitoring, duplicate control and new on-call knowledge. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Consequences may emerge after implementation and can be appended. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Record Positive and Negative Consequences”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 12 OF 16

12. Assign Follow-Up Actions and Evidence

Back to contents

Why this move matters

Name owners, due points and checks required to implement or validate the decision.

Capture why the decision exists

Name owners, due points and checks required to implement or validate the decision. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The team must define message identity, monitoring, privacy review and failure drills before rollout. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

An ADR is not a substitute for delivery tracking. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Assign Follow-Up Actions and Evidence”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 13 OF 16

13. Use Status Labels Consistently

Back to contents

Why this move matters

Define proposed, accepted, rejected, deprecated and superseded states for the repository.

Capture why the decision exists

Define proposed, accepted, rejected, deprecated and superseded states for the repository. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, ADR-014 moves from proposed to accepted after the architecture forum records its decision. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Status language should match governance reality. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Use Status Labels Consistently”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 14 OF 16

14. Link Code, Diagrams, Requirements and Operations

Back to contents

Why this move matters

Connect the ADR to the artifacts it governs without copying them into one page.

Capture why the decision exists

Connect the ADR to the artifacts it governs without copying them into one page. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, The record links to the PRD, architecture view, queue configuration, runbook and test evidence. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Links need maintenance and access control. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Link Code, Diagrams, Requirements and Operations”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 15 OF 16

15. Review Compliance and Changed Conditions

Back to contents

Why this move matters

Check whether the system follows the decision and whether its drivers still hold.

Capture why the decision exists

Check whether the system follows the decision and whether its drivers still hold. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, A later load increase and new privacy requirement trigger review of queue configuration, not silent drift. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Review frequency should reflect risk and rate of change. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Review Compliance and Changed Conditions”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

CHAPTER 16 OF 16

16. Supersede Without Erasing History

Back to contents

Why this move matters

Create a new ADR for a materially new decision and link both directions.

Capture why the decision exists

Create a new ADR for a materially new decision and link both directions. State the architectural question, current context, requirements and forces that make a durable choice necessary. Without context, a future reader sees an answer but not the problem it answered.

Compare real options on shared criteria

For the worked notification service, ADR-021 replaces the queue design after a platform change, while ADR-014 remains readable as historical context. Give each credible option the same treatment across reliability, security, cost, operational load and reversibility.

Record consequences rather than declaring victory

Explain benefits, costs, risks, follow-up work and conditions that would justify revisiting the choice. A decision can be reasonable and still create debt or limit future options.

Keep history available

Minor corrections can use change history rather than a new decision. Give the record a status, owners, date and links to superseding decisions. Preserve the old reasoning when new evidence changes the architecture.

Student, parent and career transfer

Make one evidence card for “Supersede Without Erasing History”: source location, plain-language meaning, limit and next question. A parent or teacher can ask for one everyday explanation and one specialist explanation; both must preserve the same conditions. This habit supports software engineering, cloud architecture, cybersecurity, platform engineering, data engineering, site reliability, technical leadership and quality assurance without promising a grade, admission, funding decision or job.

PRACTICE LAB

Record one technical decision

Student route

1. Write the decision question.
2. Name three drivers.
3. Describe two credible options fairly.
4. Choose one and state its consequences.
5. Add status, date and a review trigger.

Parent or teacher route

Ask whether the rejected option received fair evidence and whether the chosen option carries a visible disadvantage. Reward honest trade-offs.

Early-career route

Give the ADR to someone who missed the original meeting. If they cannot explain why the decision was reasonable at the time, add the missing context.

USEFUL NEXT READING

Connect this narrow owner to its neighbour

Read the engineering-design-rationale guide for a related but different reader job. Return here when the question is specifically how to preserve the reasoning behind a technical choice so future teams can understand, operate and responsibly revisit it. Use each guide for the reader task named in its heading.

For English practice across research, school and career communication, visit the Singapore English Tuition Centre learning site.

FREQUENTLY ASKED QUESTIONS

Questions students and parents often ask

What is an architecture decision record?

It is a short durable record of an important technical question, its context, drivers, options, decision, rationale and consequences.

How long should an ADR be?

As short as clarity allows. It should contain enough context and trade-off reasoning for a future reader to understand the choice.

Who writes it?

Any qualified team member may draft it, while the authorised decision process determines its final status.

Should rejected options be included?

Yes, when they were credible. Explain why they were not selected using the same decision criteria.

Can an ADR be edited after acceptance?

Correct minor errors and append evidence carefully, but use a superseding ADR when the decision materially changes.

Where should ADRs live?

Use an accessible, versioned central repository linked to the relevant product or code, following organisational policy.