Use Architecture Decision Records to Embrace Team Autonomy
Every software development team depends on architectural decisions. But more than often, the results of architecture discussions are never written down. This is a seed for future conflicts and software bugs, that can (and will) lead to unhappy developers and broken team productivity in the long run. But it isn’t actually too hard to create decision records that are not overly complex or hard to create.
I repeatedly noticed that senior developers or dedicated architects are often the primary deciders of architectural questions in a team. But when past decisions and assumption are only in the heads of the most experienced people, it’s hard for newcomers or junior engineers to follow the discussions. This blocks self-organized teams from being able to distribute this task across all team members. And when we consider that the process of designing a feature is sometimes a greater task than implementing it, junior engineers miss a lot! I think that a solution is to put this process more in written documentation; in this case in a process called Architectural Decision Records (ADRs).
What’s the key to taking architectural decisions? Beside practice, an important factor is having the right tool and providing a supporting environment. It’s mostly about finding all relevant questions, to somehow find answers to them, and to do informed decisions in the end. One tool and mindset is Architectural Decision Records (ADRs)—lightweight documents that introduce a topic or problem, take a decision that solves the given facts, and list what needs to be done to implement the decision.
Let’s have an example:
ADR001: Use Architecture Decision Records (ADRs) for Making Decisions
Status: approved
Context
Architectural decisions direct the future of a software project. Uninformed decisions will hurt user expectations, software stability, and longevity. Taking decisions comes with responsibilities that shouldn’t be loaded to selected individuals. Self-organized teams can take decisions as a group and have them prepared by every team member. Not everyone will be able to decide alone, but everyone should be able to participate in software architecture to a certain degree. This reduces bottlenecks and lowers the risk of discontent of team members with good ideas that were not involved.
We want to establish a mindset that enables and encourages everyone to be involved in preparing architectural decisions. It shouldn’t demand excessive knowledge or experience, or be too formal. It should not scare anyone, but embrace people to try to do more than “just” programming. Finally, this process should also build a culture where written documents are valued.
Decision
We will use Architectural Decision Records (ADRs) as our standard process to take decisions. We will provide a template that guides the authors through a set of helpful instructions that promote creativity. We will create markdown files. We will store all architecture decisions near to the topic in question (in the source code repository of the discussed component). We will store them for future reference, keep them updated, and revise them if needed. There will always be a main author, but we will still prepare them in a team effort and, finally, take informed decisions.
We will use the following template for all our future decisions:
# ADR000: [TITLE]
Status: <accepted|in progress|revised>
<!--
These documents have names that are short noun phrases. For example, "ADR001:
Deployment on Ruby on Rails 3.0.10" or "ADR009: LDAP for Multitenant Integration"
-->
## Context
<!--
This section describes the forces at play, including technological, political,
social, and project local. These forces are probably in tension, and should be
called out as such. The language in this section is value-neutral. It is simply
describing facts. -->
## Decision
<!-- This section describes our response to these forces. It is stated in full
sentences, with active voice. "We will ..." -->
## Consequences
<!-- This section describes the resulting context, after applying the decision.
All consequences should be listed here, not just the "positive" ones. A particular
decision may have positive, negative, and neutral consequences, but all of them
affect the team and project in the future. -->
<!-- This template is taken from a blog post by Michael Nygard
https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions -->
Each team member has the chance to add their voice and their opinions. The majority of us should be happy with the outcome and should to some degree be able to back it. Everyone has the divided set of resulting responsibilities. We will use our already established review and pull request workflows to review and comment the decision during creation.
Consequences
Each of our repositories should include an adrs folder and have the template stored as a blueprint.
We start to use this approach for the next architectural decision.
Decisions in question:
- General guidelines for good code.
- Design decisions about a newly designed communication protocol design.
- Architecture discussions about how to split a backend into multiple services.
- Selecting the database technology and initiating the initial schema.
- Decisions on a change process.
- Consciously decide for a coding style.
- …
We will also consider whether it is useful to convert past decisions to ADRs, if applicable, to enlarge the level of documented decisions.
Our ADRs should be as brief a reasonable to not burden the authors to write excessive amounts of texts. But they should provide a conclusive argument for a decision. It also should only be used for decisions of high importance. This is a quite fuzzy metric, but a good estimate might be the time spend in meetings that discuss a topic: Everything that isn’t decided in 10 minutes might qualify for an ADR.
Will we get rid of architects? Certainly not. After all, there will always be value in experienced architects or authorities such as architecture boards (see also Scaling Architecture Conversationally by Andrew Harmel-Law). Also not everyone in a team might want to take this writing-centered tasks. But it will contribute to democratize the process of doing architecture decisions. It might be a good tool to establish a healthy documentation practice where individual expertise is converted to long-lasting common knowledge, however, I can’t promise to have found the holy grail to make everyone love to document stuff. As a bonus, having a process that can potentially involve many people in a team or company increases the likelihood to design a good (and ethical) product.
In my last project, we used ADRs for our key decisions and I keep seeing the benefits in my current work. This approach helps me to structure my thoughts and think about architectural ideas before starting to write any code. It is also a valuable reference for the future and for new team members to understand how certain things are supposed to work. The best thing is that one automatically documented the reasoning of a decision and have it stored for future reference without any additional effort—and finally no more discussions about “Oh, I thought we agreed to doing it this way…“.
The template is based on a blog post by Michael Nygard. I first encountered it in Backstage and am happily using it since then.