An architecture decision (AD) is a software design choice of introducing a significant change in the architecture.
The architecture decision record (ADR) is a formalized document that captures and explains this design choice and its impacts.
It comes with an engineering process describing how to make these decisions and record them.
Why using ADR?
When working on a large software codebase, it may be hard to know why the architecture has been designed this way in the first place.
The project's context is evolving. We handle more functional use cases, more data, more users, the architecture looks irrelevant or limited. The teams are changing; new engineers joined, some elders left. Can we change this aspect of the architecture? What are the impacts?
ADR is a robust documentation foundation allowing your team to share and understand the former technical decisions. It also supports the team's alignment on how the current architecture should evolve to answer tomorrow's needs.
How to deploy ADR in your organization?
You can deploy architecture decision records by establishing a four-step workflow: identify the decisions, make the decisions, document the decisions, and share them.
1. Identify
Define what kind of architecture decisions should follow your ADR process. Usually, we're talking here of a large change impacting the whole architecture: replace the storage system, introducing a new language or a new framework, integrate a new technical component, etc
Explain to the team how to identify a potential decision. As well as how the decision will be made and how to record and track its resolution.
2. Make the Decision
Describe the current context, the limitations, the potential changes, the pros/cons, the expected benefits, and impact. You should use a template to articulate the pieces of information that need to be collected to make the decision. Involve the group of people to make the decision.
3. Document
Record the decision in your architecture decision records repository. This space has to be known by all the teammates and has to be up to date.
4. Share
Ensure the decision is known and understood by the engineering team and by the groups impacted by this decision. The ADR should be self-explanatory to understand the reasoning behind the architecture decision.