Course contentsShow
← Software Engineering
Lesson 1700 of 1,93349. Technical Writing and DocumentationFree lesson

When to Write an ADR

Identify which decisions warrant an ADR: structural changes, technology choices, and significant trade-offs.

When to Write an ADR

What you'll learn: You'll discover which technical decisions deserve formal documentation as Architecture Decision Records.


Not every decision needs an ADR. Writing too many creates noise; writing too few leaves critical context undocumented. The key is recognizing which decisions have lasting impact on your system's shape and direction.

Decisions That Warrant an ADR

Structural Changes

If a decision affects how major components relate to each other, write an ADR. Examples include:

  • Moving from a monolith to microservices
  • Introducing an event-driven architecture
  • Changing your data storage layer's organization
  • Adopting a new deployment model

Think of it this way: If the decision changes the "skeleton" of your system, it deserves documentation.

Technology Choices

Selecting technologies with long-term consequences requires an ADR:

  • Choosing a primary programming language or framework
  • Adopting a database system
  • Selecting a message queue or caching solution
  • Committing to a cloud provider

These choices create technical debt if reversed, so documenting the "why" becomes crucial.

Significant Trade-offs

When you make a decision that explicitly accepts one disadvantage to gain an advantage elsewhere, document it:

  • Choosing eventual consistency over strong consistency for performance
  • Accepting increased complexity for better scalability
  • Trading development speed for runtime efficiency

The ADR captures what you knew at decision time and what you considered acceptable.

What Doesn't Need an ADR

Skip ADRs for routine implementation details, reversible choices, or decisions limited to a single component's internals. Not every technical choice is architectural.


Key Takeaway: Write an ADR when a decision has structural impact, involves significant technology choices, or represents an important trade-off that future engineers will need to understand and potentially revisit.