Part 2: Troubleshooting our Architecture Decision Process

This is the second post of a four-part blog series about how the One Medical technology team uses Architecture Decision Records.

By Amber Houle and Jeff Ammons

One Medical started using Architecture Decision Records (ADRs) as a tool to help us make better decisions and to document the what and why behind those decisions. See Part 1 of this series for more details on how we started this process.

We initially saw success with this process. However, after a few months, we started to see some problems arise — some decisions were getting stuck. There were a lot of comments on the pull requests and lots of good back and forth discussion, but the decision hadn’t been finalized.

Investigating this, we started to hear a pattern: people weren’t sure how to handle situations where there was disagreement on the solution proposed. It wasn’t clear how many approvals were needed and from whom in order to proceed. In at least one case, someone pushed forward and merged a decision, which ended up having to be reversed after other engineers pointed out concerns that hadn’t been addressed.

For us to move forward as a high-functioning engineering team, we needed to be able to make great decisions while moving quickly. We needed to better define what our expectations and processes were for making hard decisions.

Defining the process

The goals of the ADR process still remained, but we needed to find a way to avoid getting stuck. This is really a cultural question as well as a decision-quality question. There are a lot of ways to arrive at a decision — some examples you’ve likely encountered include: the highest-ranking person gets to make all the decisions, the group votes to decide, you flip a coin, etc. Clearly, each of these have consequences for the quality of decision that is made, and also for how the participants will feel about committing to the decision.

Our culture at One Medical is very collaborative. We believe that small groups of people can build better solutions than individuals in isolation. Any solution we came up with needed to allow for this. Yet, we also didn’t want to have every decision made by consensus, which would take forever. Committee design can often lead to worse decisions as well. So how can we be inclusive and harvest our collective knowledge, while also avoiding the need for 100+ engineers to decide on every detail?

We decided to split the process into three sections: a broadly inclusive creation of the proposal, final decision making by a small group, and lastly, communication of the final decision.

Each of the first two sections follow a similar pattern borrowed from the double-diamond design process. Each section involves going broad to collect information and perspectives, followed by narrowing focus into producing something concrete — firstly the proposal, then secondly, the decision record.

Roles

Before getting into the details of our architecture decision process, it’s worth defining two roles: the individual leading the decision process and the group formalizing the final decision.

Decision Leads

The decision lead is the engineer responsible for initiating and following the architecture decision process from start to finish. They are the one driving the decision forward to a successful conclusion. This likely means they are defining the problem, doing research, talking with other engineers or stakeholders, documenting possible directions, addressing comments, and later sharing the decision with the broader group (plus anything else necessary to get to a good decision quickly).

At One Medical, anyone can serve as a decision lead; the only requirements to fill the role are having a problem that requires a decision and a willingness to put time and effort into following this guide. This was an intentional decision — we want everyone to feel empowered to make changes and advocate for improvements to our system.

Architecture Councils

The architecture council is a semi-permanent group of engineers oriented around a particular area of focus. These groups aim to provide consistency of vision, diversity of perspectives, and depth of knowledge to the decision-making process.

These groups are not meant to originate architecture decisions — that will be left to decision owners on teams or guilds which have clear and present needs for decisions. But members of the councils can be decision owners if their team’s work necessitates it.

Each council has four permanent members. One member of each council will rotate off every six months and a new member will be added.

Up Next:

Check out Part 3 of this series: Our Architecture Decision Process and follow One Medical Technology for more upcoming posts from our technology team!