Architectural Decision Record (ADR): A Vital Decision Document for Your Project’s Success

What is an Architectural Decision Record?

To better understand what an ADR is, we can rely on some definitions provided by important organizations in the IT sector. According to GitHub organization, An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. Spotify, on the other hand, states that An Architecture Decision Record (ADR) is a document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision. If you want the complete picture you can also take a look at the definitions from Google and AWS.

Summarizing the main points of each, we point out that in this article by ADR we mean “a document describing all the architectural decisions made about a piece of software, usually flanked by the context and goal that led to those decisions“.

Benefits of an Architectural Decision Record

An ADR brings several benefits to organizations. Such benefits can be experimented with both in writing and reading an ADR. Let’s take a look at these advantages.

Benefits of writing an ADR

• Helps identify the knowledge gap for a decision to be made;
• Forces you to explain and justify the decisions you want to make;
• Suggests options that you were not considering;
• Guides teams to share technical solutions;
• Allows you to think long-term and not day-by-day;
• Can be used to inform development teams about best practices and other areas such as the security team so that they are aligned.

Benefits of reading an ADR

• Facilitates the onboarding process;
• It removes the need to have a person who knows all the information, and you can consult the document directly;
• Allows you to check whether some choices have already been considered in the past;
• Can be used with stakeholders to justify one’s choices or initiatives.

Risks of an ADR

As with any other tool, an ADR brings you benefits but also introduces new risks. The risks to be aware of are: being out of date and too rigid. Let’s find out why and how to avoid these risks.

If the document is not updated regularly, all the benefits of having a system to share knowledge of the architectural choices made will be lost, the document will be inconsistent, and the teams will find no benefit in using it. It is important to make sure that teams consult the ADR to detect any inconsistencies in time and create a step for reviewing this document during the design phases to make sure that it is not forgotten to be updated.

Excessive rigidity: keeping track of decisions could create a process of validating architectural choices that slow down development processes too much. To avoid this, one must remember that ADR is a knowledge-sharing system, so the important thing is not to make the best decision at the expense of time, but to track the choice made whatever it is.

When you need an Architectural Decision Record

ADR can be applied on two levels that are not mutually exclusive: High Level and/or Low Level.

Low Level includes all those decisions made within a single service/repository. In this case, the ADR can be found within the same repository as the code. Within it, all key decisions made during development should be tracked, for example:

• Why a particular library has been chosen for this project;
• The criteria for splitting files within the project;
• The naming conventions to be followed.

Instead, by High Level we mean all decisions made in an IT architecture that integrates multiple software, components, or plugins. For example:

• The use of ready-to-use components from a third-party company at the expense of in-house development of custom components;
• The functions and responsibilities of a single application;
• How the communication between the components takes place, whether synchronously or asynchronously;
• The choice to use a message broker and why.

In the context of a company where multiple vendors and multiple developers are involved, each of whom must undertake architectural choices, ADR is typically applied on High Level, to govern this complex process.

Real-world examples

Architectural choices can follow two different paths:

• Top-down: some architectural decisions, especially those regarding the tools and technologies that can be used, cannot be made independently by the teams developing on the platform e.g., the use of a particular Message Broker rather than another. This is because some factors such as licensing, commercial agreements, or infrastructure costs may drive this process.
• Bottom-up: in other cases, however, the need may arise for a team to make an architectural change. Examples might be the development of a plugin on the platform for sending emails, or a manager for file storage. In this case, the team might submit a request or proposal to be validated and then implemented.

In the bottom-up process, it is important to emphasize that ADR should have the sole purpose of tracking choices and proposals to share knowledge, and not to slow down decisions. Below are two examples to better clarify the concept: the first one illustrates the process for reusing a plugin, the second one the process to create a new one.

Reusing a plugin
A team presents a need to send emails on their application and checks on the ADR to see if there is a best practice for sending emails. From this check on the ADR, they discover that a plugin for sending emails is already existing within the platform. So, the plugin is adapted to the particular use case and they use it for their application.

Creating a custom plugin
Another team presents the need to have to send emails on their application and checks on the ADR. As the team from before, they learn about the already existing plugin. The plugin in this case is not adequate for their use case, because it lacks a key feature. Evolving the plugin would require too much cost, and the team decides to use a custom solution.
Again, the team must update the ADR to track this decision and the rationale behind it.

As the example shows, ADR is very important both for disseminating best practices and for explaining why these are not being followed. In the second case, ADR becomes very useful for two reasons. First of all, to track the missing feature for which the plugin has not been used. At a later time, when this feature is integrated on the plugin and embedded in the application, to track on the ADR that that software is using the platform plugin.

What to include in an Architectural Decision Record

A minimum set of information to be kept for each individual decision must be established, which can be adjusted for different use cases. Taking Michael Nygard’s template as an example, one would need to keep track of, at least, the following information:

• Status of the decision;
• Context: What are the reasons and the necessities for making or proposing this decision;
• Decision: What will be actually implemented/discarded and how;
• Consequences: What will become easier and harder to do with this decision.

This way we are sure to keep track of all the decisions made as well as the reasons for making a certain choice.

How to share the Architectural Decision Record

The first issue to be addressed in the creation and management of ADR concerns the sharing of information within the company and with all relevant development teams. The ideal option would be to identify an already common point where developers share documentation and leverage that for ADR as well.

In case this is not present or not deemed adequate, a “crude” solution is to adopt a repository where all architectural choices are tracked. Instead, a more structured choice is to use a Developer Portal for sharing documentation, including ADR.

Choosing a Developer Portal that also contains ADR would also bring the following benefits:

• Clearly structured and detailed documentation: A Developer Portal makes it possible to provide comprehensive, well-structured documentation that brings together in one place the technical and business descriptions of the features, systems, Kafka topics, and APIs offered by the company. This helps developers quickly understand how to use APIs in the right way, reducing the time needed for integration.
• Code samples and tutorials: A Developer Portal should offer code samples and tutorials that illustrate the practical implementation of APIs. These examples allow developers to have detailed guidance on how to use the API within their projects.
• API promotion and adoption: Adopting a Developer Portal helps to understand what functionality is already exposed and how to access it through existing APIs. By providing clear documentation, code samples, and adequate support, companies can then increase the adoption of their APIs and create an active developer ecosystem around their services.
• Version and authentication management: A Developer Portal can facilitate the management of service versions by documenting what features are supported in each one and highlighting version breaking. This will allow developers to migrate to new versions in a controlled manner. In addition, tools can be integrated to manage authentication and authorization of the various exposed APIs, ensuring their security and access control.

Conclusion

A well established Architectural Decision Record can be the key to the success of your projects. An ADR helps your teams and all stakeholders involved be aligned on all key decisions and the reasons behind them. While this is good for productivity, it also benefits the morale of the team and the Developer Experience, making sure that each team member feels part of what they are building.

Choosing a Developer Portal as the common point where to store the ADR is the best option to help your teams keep track of the decision with the least switch of context possible. But a Developer Portal can help you and your team in many other ways. Take a look at this article to discover 5 tips for implementing an Internal Developer Portal in your company.