Several teams at Spotify use architecture decision records (ADR) to capture decisions they make. ADRs have brought a number of benefits to Spotify, including improved onboarding for new developers, improved agility when handing over project ownership due to organization changes, and improved alignment across teams regarding best practices.
An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
Architectural decision records are a technique that is often used in agile contexts, due to their constantly evolving nature. As agile expert Michael Nygard wrote,
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.
Architecture decision records include information to understand the context that led to a given decision as well as its consequences. Additionally, they can also document decisions that were not made and the reasons why.
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, says Spotify engineer Josef Blake. In his experience, there are at least three scenarios where writing an ADR should be a no-brainer.
First of all, you will want to write an ADR to capture a past decision that was not documented. This will ensure it will be clear to everyone that that decision exists.
Similarly, if a decision was made but it was never recorded, can it be a standard? One way to identify an undocumented decision is during Peer Review. The introduction of a competing code pattern or library could lead the reviewer to discover an undocumented decision.
Often, writing an ADR is the final step in the process of making a change that will have a large impact on a system, for example a change that would break an API. In such cases, Spotify engineers use to write request for comments (RFC) as a means to facilitate all stakeholders to agree on a common approach. Once the RFC process is completed, the solution agreed upon is captured in an ADR.
ADRs should not be written only for decisions with a large impact, though, remarks Blake.
The cost of undocumented decisions is hard to measure, but the effects usually include duplicated efforts (other engineers try to solve the same problems) or competing solutions (two third-party libraries that do the same thing).
In such cases, writing an ADR has the added benefit of not being particularly complex.
Architectural decision records are by no means a novel technique. In particular, lightweight decision records were on ThoughtWorks's technology radar for a couple of years. If you are interested in giving it a try, you can find additional information as well as ready-to-use templates in this repository.