Subscribe to the feed

When they are working on a new feature, project leaders—whether open or closed source—need to decide how to implement it. Agile projects often make decisions on the fly, unlike the old waterfall world, where a long requirement-engineering phase precedes the development process. Often enough, the why and how of the feature are kept in the decision-making developer's brain. Newcomers to the project then are left to wonder why certain things are done in a certain way, making it hard for them to figure out and contribute, as the necessary knowledge is not readily available.

Michael Nygard identified this issue back in 2011 in his article Documenting architecture decisions, where he presents the concept of architecture decision records (ADRs).

Architecture Decision Record

The need for such records increases for larger or more distributed projects, especially those where no single architect is available or where new contributors are being onboarded. The time was ripe for such a format when Nygard wrote his article, and seven years later, IT consultancy Thoughtworks put ADRs into the Adopt category of its technology radar.

As the name ADR suggests, you use these records for making larger architectural decisions. They don't serve as a glorified change log or replace (good) commit messages.

Components of an ADR

This image shows the general components of an ADR:

Architecture Decision Record details
  • Number/Date: A unique increasing number and date that usually follows the ADR-nnnn pattern to help sort them from old to new
  • Title: Indicates the content
  • Context (Why): Describes the current situation and why you made this decision or thought it necessary—some variations explicitly break out an "alternatives covered" section to ensure all considerations get recorded
  • Decision (What/How): Describes the what and how of the feature
  • Status: Describes the status; note that ADRs can be superseded later by newer ADRs
  • Consequences: Describes the effect of the decision, listing positive and negative aspects

While decision records contain the "technical" decisions, they should also list non-functional ones. They can also include the decision to use an ADR in the first place or the license chosen. You can find an example of this in the Operate First project's repository.

ADR formats

The previous section describes the basic format of an ADR. Over time, many ADR formats and templates have evolved. The ADR repository on GitHub lists some of them and some templates. Common to all is using a (lightweight) markup language like AsciiDoc.

Much more important than the concrete format you choose is where you put the records. It is best to put them next to the source code in your project in a dedicated ADR folder in the documentation. Of course, that isn't possible for projects with multiple repositories. There, the best option is to use the main repository and link it into the README of the dependent projects.

ODF and ADR

The Open Decision Framework (ODF) is a framework for making decisions openly and inclusively. Using ODF for minor projects may be overkill, but once your project targets multiple stakeholders and parties, ODF becomes a powerful tool.

Interestingly, the group of people likely to use ODF are the same people who benefit from ADRs. In fact, ODF encourages sharing decisions made openly. And ADRs can be a powerful way of doing so.

Open Decision Framework and Architecture Decision Record

Wrap up

You can use ADRs during the ODF feedback loop: Put a draft of the decision with documentation of constraints, goals, and such into a pull request, and then update this alongside the feedback rounds. Once you make your decision, you can merge the pull request into the main repository.

For more information, read:


About the author

Heiko is a long-time open source committer. He currently works for Red Hat on the topic of monitoring and management of server and software systems. Heiko has received a master's in Computer Science from the University of Karlsruhe and has written two books on JBoss AS and Enterprise Java Beans.

Read full bio
UI_Icon-Red_Hat-Close-A-Black-RGB

Browse by channel

automation icon

Automation

The latest on IT automation for tech, teams, and environments

AI icon

Artificial intelligence

Updates on the platforms that free customers to run AI workloads anywhere

open hybrid cloud icon

Open hybrid cloud

Explore how we build a more flexible future with hybrid cloud

security icon

Security

The latest on how we reduce risks across environments and technologies

edge icon

Edge computing

Updates on the platforms that simplify operations at the edge

Infrastructure icon

Infrastructure

The latest on the world’s leading enterprise Linux platform

application development icon

Applications

Inside our solutions to the toughest application challenges

Original series icon

Original shows

Entertaining stories from the makers and leaders in enterprise tech