Recently, I was exposed to Architectural Decision Records (ADRs) as a way to document software architecture decisions quickly and effectively. The more I’ve learned, the more I like.
Building Evolutionary Architectures
Architecture, software or otherwise, is typically a tedious and time-consuming process. We must design to meet existing requirements, but have to anticipate potential future requirements without creating an overly complex (i.e. expensive) system. This is typically accomplished through a variety of patterns which aim to decouple components and make them easily replaceable.
Replace it?!? Everything ages, even software. If I have learned one thing, it is that the code you write today “should” not exist in its same form in the future. All code needs to change and evolve as the platforms and frameworks we use change and evolve. Building Evolutionary Architectures is a great read for any software engineer, but I would suggest it to be required reading for any software architect.
How architecture is documented and communicated has evolved in the last 30 years. The IEEE published an excellent white paper outlining how early architecture practices have evolved into these ADRs.
But what IS it?
Architectural Decision Records (ADRs) are, quite simply, records of decisions made that affect the architecture of the system. ADRs are simple text documents with a concise format that anyone (architect, engineer, or otherwise) can consume quickly. ADRs are stored next to the code (in the same repository), so they are subject to the same peer review process. Additionally, ADRs add the ability to track decisions and changes over time.
Let’s consider a simple example, taken straight from the adr-manager tool used to create ADRs in a GitHub repository. The context/problem is pretty simple:
We want to record architectural decisions made in this project. Which format and structure should these records follow?
The document then outlines some potential options for tracking architectural decisions. In the end, the document states that MADR 2.1.2 will be used, and outlines the rationale behind the decision.
It may seem trivial, but putting this document in the repository, accessible to all, gives great visibility to the decision. Changes, if any, are subject to peer review.
Now, in this case, say 6 months down the road the team decides that they hate MADR 2.1.2 and want to use Y-Statements instead. That’s easy: create a new ADR that supersedes the old one. In the new ADR, the same content should exist: what’s the problem, what are our options, and define the final decision and rationale. Link the two so that it’s easy to see related ADRs, and you are ready to go.
Tools of the Trade
There is an ADR GitHub organization that is focused on standardizing some of the nomenclature around ADRs. The page includes links to several articles and blog posts dedicated to describing ADRs and how to implement and use them within your organization. Additionally, the organization has started to collect and improve upon some of the tooling for supporting an ADR process. One that I found beneficial is ADR-Manager.
ADR-Manager is a simple website that lets you interact with your GitHub repositories (using your own GitHub credentials) to create and edit ADRs. Through your browser, you connect to your repositories and view/edit ADR documents. It generates MADR-styled files within your repository which can be committed to branches with appropriate comments.
Make it so…
As I work to get my feet under me in my new role, the idea of starting to use ADRs has gained some traction. As we continue to scale, having these decision records readily available for new teams will be important to maintain consistency across the platform.
As I continue to work through my home projects, I will use ADRs to document decisions I make in those projects. While no one may read them, it’s a good habit to build.
Leave a Reply