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

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).

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:

• 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.

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:

• How to write effective documentation for your open source project
• Operate First Blueprint