Documenting architectural decisions helps a project succeed by helping current and future contributors understand the reasons for doing things a certain way.
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.
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:
You should be a part of a contest for one of the most useful websites on the web. I am going to recommend this website!
Someone truly assisted in the creation of outstanding articles. I must say that this is the very first time I have visited your website, and thus far I am astounded by the research you conducted to produce this exceptional post. Well done!