NEW: English for Tech Bundle → Save 40%
Speak Tech English
Book class
Your progress…

Loading your progress…

Home
Planning & Processabbreviation · /ˌeɪ.diːˈɑːr/

ADR

In simple English

ADRs are lightweight documents that teams use to document significant technical decisions and their trade-offs. Rather than storing this knowledge only in people's heads or scattered across emails and chat messages, ADRs create a permanent, searchable record that helps new team members understand the system architecture and why certain choices were made. Each ADR typically includes the decision, the context (problem being solved), the options considered, the chosen solution, and the consequences or trade-offs. ADRs are especially valuable in distributed teams and for long-term project sustainability, as they prevent repeated discussions of the same architectural questions and provide clear justification for design choices that might otherwise seem arbitrary to newcomers.

What is an ADR and how do I document architectural decisions in my software project?

At a glanceCEFR B2
Commonness4/5
Versatility4/5
FormalityCasualFormalNeutral
Spoken ↔ WrittenSpokenWrittenBoth
Directness ↔ DiplomaticDirectDiplomaticDirect
RegionUS and UK
New app · Free lessons

Speak up in meetings. Feel confident.

Standup vocabulary, native examples, and quick practice — 100+ free lessons

Start learning freeNo card needed · Google or email
MemberMemberMember

3,000+ tech pros preparing for global tech roles

Lessons · Quizzes · Progress

Say it like this

✓We should write an ADR for this decision
✓Let me check the ADR for that architectural choice
✓This ADR documents the reasoning behind our microservices approach

Real examples

in a design meeting

"Before we move forward, we need to create an ADR explaining why we are switching to a serverless architecture."

in a code review

"The ADR clearly states that we chose REST over GraphQL for API simplicity, so this implementation is correct."

in onboarding a new developer

"Read the ADRs in our docs folder to understand the architectural decisions made over the past two years."

Don't say this

Handle with care. ADR is often confused with decision logs or design documents. ADRs specifically document the reasoning behind architectural choices, not all decisions. Do not use ADR for minor implementation choices.

✕We will use an ADR to decide between two database options.
✓We will make a decision between two database options and then document it in an ADR.— ADRs document decisions already made, not the decision-making process itself. They record the outcome and reasoning.
✕I wrote an ADR for the bug fix we shipped today.
✓I wrote an ADR for our decision to refactor the authentication module.— ADRs are for significant architectural or technical decisions, not routine bug fixes or minor code changes.
✕Our ADR says we should use microservices, so let us do it.
✓Our ADR documents why we chose microservices for this system based on our scalability requirements.— ADRs explain the reasoning and context, not just the decision itself. They should help others understand the trade-offs.

Other forms

noun

ADR

"The ADR for our caching strategy is documented in the architecture folder."

noun

ADRs

"Our team reviews ADRs during architecture discussions."

Often used with

write an ADRUsed when creating a new architecture decision record
document in an ADRDescribing the act of recording a decision formally
ADR proposesWhen referring to the suggestion or solution within an ADR
follow the ADRImplementing the decision documented in an ADR
review the ADRsExamining existing architecture decision records

Similar words

design decision logBroader term for documenting design choices; ADR is more specific and structured
decision recordGeneral term; ADR specifically focuses on architectural decisions
architecture documentationBroader category that may include ADRs along with other documentation

Featured course

English for Developers Bundle

Full tech-English bundle for meetings, code reviews, and everyday developer communication.

500+ reviews

View

Practice

Try it

4 quick exercises

Pick the most natural phrasing

1. Your team chose to use Kubernetes for orchestration. What do you do next?

Complete the sentence

2. The _______ documents why we decided to use event-driven architecture instead of request-response.

Spot the mistake

3. Which sentence uses ADR incorrectly?

Rewrite naturally

4. Rewrite this using ADR: 'We made a decision to use PostgreSQL instead of MongoDB because it is better for structured data, and we should write something down about this choice so people know why we chose it.'

Questions

Quick poll

Have you said "adr" in a standup this week?

Want more structured practice like this? Our English for Programmers course covers real workplace English in depth.

Your badges

XLinkedIn
← Back to home