Skip to main content

Why you should be using architecture decision records to document your project

Documenting architectural decisions helps a project succeed by helping current and future contributors understand the reasons for doing things a certain way.
Chess board

Photo by HARUN BENLİ from Pexels

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
(Heiko Rupp, CC BY-SA 4.0)

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.

[ Three-fifths of organizations are making automation a top initiative. If this describes you, learn 6 ways to promote organization-wide IT automation. ]

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
(Heiko Rupp, CC BY-SA 4.0)

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.


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
(Heiko Rupp, CC BY-SA 4.0)

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:

Author’s photo

Heiko W. Rupp

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. More about me

Navigate the shifting technology landscape. Read An architect's guide to multicloud infrastructure.


Privacy Statement