What is Architecture Decision Record (ADR)? Do I need it? How is it useful?
Architecture Decision Record is a term I had started hearing a lot recently. Maybe it's my interest which started me driving towards this term or something else.
Since we live in the world of agile development now how does that affect our architectural decisions. Do we take all the decision at once? Do we have answers for all our questions before even we start? Are our systems designed only once? Many of these questions will always reply back with a “NO”.
Architecture for agile projects has to be described and defined differently. Not all decisions will be made at once, nor will all of them be done when the project begins.
So how do we capture this between multiple teams involved in development cycle? How do we retain this information of why this decision was taken 10 years from now? How do we avoid answering the same question again again? The best and simple answer for all these questions is to document them. And that’s when we can say how do we do it? We can use ADR to do it.
Let's start looking into some of the terms we would be coming across while we start understanding ADR.
What is Architectural Decision?
An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
What is Architecture Decision Log?
An Architecture Decision Log (ADL) is the collection of all ADRs created and maintained for a particular project (or organization).
What is Architectural Decision Record?
An Architectural Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
What is Architecturally-Significant Requirement?
An Architecturally-Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture.
Now that we understand terminologies like AD, ADL, ADR, ASR.
When should I write an Architecture Decision Record (ADR)?
If you have made a significant architectural decision that impacts how engineers write software then write a ADR. ADR’s are used to document decisions made related to system design and engineering best practices. To arrive at these decisions team can have several meetings, whiteboards, etc.
What are Request for Comments (RFC)?
An RFC (Request for Comments) in information and communications technology, is a type of text document from the technology community. An RFC document may come from many bodies including from the Internet Engineering Task Force (IETF), the Internet Research Task Force (IRTF), the Internet Architecture Board (IAB), or from independent authors.
What are the benefits of ADRs?
Few of the benefits of using ADRs are -
Onboarding : Future team members will able to read a history of decisions and quickly get up to speed on how and why a decision is made, and the impact of that decision.
Ownership Handover : While working in a agile environment we always aim to learn fast. In this environment, we don’t hesitate to implement organizational change to meet the needs of our customers as it evolves. When our organization changes, we sometimes have to move ownership of systems from one team to another. So, a lot of context or knowledge would be lost when this takes place, triggering a decrease in productivity. This problem will become less severe with the introduction of ADRs. New owners of a system can quickly get up to speed with how and why the system’s architecture evolved in the way it did simply by reading through the ADRs.
Alignment : ADRs will make it easier for teams to align on best practices. Alignment has the benefit of removing duplicative efforts, making code reusable across projects, and reducing the variance of solutions that central teams need to support.
But when should I write one?
An ADR should be written whenever a decision of significant impact is made; it is up to each team to align on what defines a significant impact.
Deciding when an ADR should be written is not always easy to do, since there are multiple ways of understanding when a decision has a significant impact on a project.
There are at least 3 scenarios where writing an ADR should be a no-brainer.
Backfilling decisions: Sometimes a decision was made, or an implicit standard forms naturally on its own, but because it was never documented, it’s not clear to everyone (especially new hires) that this decision exists. So, if a decision was made but it was never recorded, can’t it be a standard? One way to identify an undocumented decision is during Peer Review. In order to model for when to backfill an architecture decision:
1. Do I have a problem? No
2. Is there a blessed solution? Yes
3. Is it documented? No
4. Write an ADR.
Proposing large changes: Over the lifecycle of a system, you will have to make decisions that have a large impact on how it is designed, maintained, extended, and more. As requirements evolve, you may need to introduce a breaking change, which would require a migration from your consumers. We have system design reviews, architecture reviews, and RFCs to facilitate agreements on an approach or implementation. When these processes run their course, how should we capture the decisions made? In order to model for how to document these large changes:
- Do I have a problem? Yes
- Is there a blessed solution? No
- Do I have a solution? Yes
- Is it a big change? Yes
- Write an RFC!
- Did my RFC conclude with a solution? Yes
- Write an ADR!
Proposing small/no changes: In our day-to-day, we make decisions that have little to no impact. The cost of undocumented decisions is hard to measure, but the effects usually include duplicated efforts (trying to solve the same problems) or competing solutions (two third-party libraries that do the same thing. Enough small decisions can compound into a future problem that requires a large process or effort (ie. migration). Documenting these decisions doesn’t have to cost much. ADRs can be lightweight. In order to model for how to document these small or no changes:
- Do I have a problem? Yes
- Is there a blessed solution? No
- Do I have a solution? Yes
- Is it a big change? No
- Write an ADR.
Flowchart when we should write a Architecture Decision Record
ADR Template
# Title
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —## Status
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?## Context
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
What is the issue that we’re seeing that is motivating this decision or change?## Decision
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
What is the change that we’re proposing and/or doing?## Consequences
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
What becomes easier or more difficult to do because of this change?
What should be considered while writing a good ADR?
Characteristics of a good ADR:
- Point in Time — Identify when the AD was made
- Rationality — Explain the reason for making the particular AD
- Immutable record — The decisions made in a previously published ADR should not be altered
- Specificity — Each ADR should be about a single AD
Characteristics of a good context in an ADR:
- Explain your organization’s situation and business priorities
- Include rationale and considerations based on social and skills makeups of your teams
Characteristics of good Consequences in an ADR:
- Right approach — “We need to start doing X instead of Y”
- Wrong approach — Do not explain the AD in terms of “Pros” and “Cons” of having made the particular AD
Note: When an new AD is made that replaces or invalidates a previous ADR, a new ADR should be created.
Where to store ADRs?
The best place ADRs according to me should be where all the team documentation is stored. I like storing my documentation in my source code repositories (which maintains versioning).
Summary
The most important thing to document in these design records is not what you decided to do, it’s what you considered and decided not to do. You want there to be a record of the other options that were considered, what their perceived pros and cons were, and ultimately why they weren’t chosen. This is something you and others can review later and if the circumstances haven’t changed substantially, the decision should probably stand. If new information has surfaced that renders the original decision obsolete, it should be obvious based on the information in the record.
