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.
What are Architectural Decision Records?
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).
How and Where to Use ADRs?
There are various areas one can use ADRs in a project and a number of steps one can take to implement them:
Decision enforcement and enactment
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.
Decision-sharing
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.
Decision documentation
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.
Decision guidance
Quite a few decision-making techniques exist. These include general techniques and software architecture-specific ones, such as dialogue mapping.
Identifying decisions
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.
Architectural Decision Record Example
To give you a brief example of how am ADR might look like, I've added an example:
# 1. Use Typescript for all JS related tasks
## Status
Accepted
## Context
The Frontend Team encountered that the Frontend Code Base is growing too fast. Due to that, the code quality suffers.
## Decision
Introducing a static-typed language as a superset of Javascript shall help to deal with this situation. All JS related tasks will now be written in TypeScript.
## Consequences
All components of the Frontend Workflow have to be refactored to the new built. In addition, all old plain js files should be rewritten in TypeScript.
Top comments (2)
Hey David, huge fan of ADRs, thanks for writing this up. Curious are you still using ADRs? I've been working on some tooling in this space and would love your thoughts.
Hi Morgan,
I still use ADR's whenever it makes sense. I strong believe in well structured code following common best practices. Besides that, there is not much to document except decisions made during development. Therefore ADR's is a great fit to fill the knowledge gap.