Developers know that software architecture is important stuff.
For novice developers, though, there may be a bit of confusion on how much control one may have in the architecture of a piece of software. This is where Architectural Decision Records come in.
But just what are ADRs, and why are they so important for developers to learn about? Let’s dive into everything you need to know about ADRs.
Architectural Decision Records (ADRs) are documents that capture a vital architectural decision made, plus its context and consequences. ADRs are common practice in software development and software architecture. ADRs are typically used in addition to common documentation but provide a sort of history.
An Architectural Decision (AD) itself is a software design choice, one that addresses an important requirement in the system. Architectural Decision Logs (ADL) are collections of all ADRs that have been created and maintained for a certain project or organization. An Architecturally Significant Requirement (ASR) is a specific requirement that has a quantifiable effect on the architecture of a software system. All of these titles are used within the topic of architecture knowledge management (AKM).
There are various areas one can use ADRs in a project and a number of steps one can take to implement them:
ADs are used primarily in software design, so they have to be communicated to and accepted by the people that fund, develop, and operate the system. This often includes sponsors, stakeholders, and producers but also the developer team itself.
Architecturally apparent coding styles and code reviews will need to be implemented. They should focus on architectural concerns and decisions. ADs also have to be considered when modernizing a software system in software evolution and implementing new elements.
Using ADRs for decision-sharing is definitely optional, but many ADs reoccur across projects. Because of this, experiences with past decisions in the project can be valuable assets when employing a new and outward knowledge management strategy. Keep in mind that group decision making is often an active research topic.
Many templates and tools for decision capturing exist. Look into agile communities, such as M. Nygard's ADRs. You can also look into traditional software engineering and architecture design processes, such as table layouts suggested by IBM.
Quite a few decision-making techniques exist. These include general techniques and software architecture-specific ones, such as dialogue mapping.
Ask yourself (or your team): Just how urgent and how important is the architectural design for this project? Does it have to be figured out now, or can it wait until we can figure more stuff out?
This is where having a good team in. Having a mix of personal and collective experience, in addition to recognized design methods and practices, can help substantially with decision identification.
Ideally, you should create and maintain a decision backlog that works with the product backlog.
To give you a brief example of how am ADR might look like, I've added an example: