Part 1: Adopting Architecture Decision Records within your technology team

This the first part of a four-part blog series about how the One Medical technology team uses Architecture Decision Records (ADRs).

By Amber Houle and Jeff Ammons

The One Medical technology team has grown quite a bit in the last few years. With growth comes change, and inevitably, some level of growing pains. As new engineers joined the team, it became more and more difficult to rely on implicit institutional knowledge to onboard new team members and share context on historic technical decisions that were made.

New engineers joining the technology team would ask questions like:

• Why was Ruby chosen over Python for this service?
• Why was GraphQL introduced in this context?
• What javascript framework should be used moving forward given several frameworks are already adopted?

We found ourselves having the same discussions repeatedly, and in some cases struggling to find the right people who knew the answers to these questions and why the decisions were made in the first place.

In order to ensure engineers were well equipped to make sound technology choices and architecture decisions moving forward, we needed a clear process for making and documenting these decisions.

The Solution

We ultimately landed on a simple Architecture Decision Record (ADR) — a document which captures the problem context, decision drivers, pros and cons of various considered options, as well as the decision outcome.

There is already an abundance of information on what Architecture Decision Records are, so we won’t go into detail here, but some good references are the ADR Github Organization and Joel Parker Henderson’s ADR Github Repository.

In order to make it easy for teams to adopt Architecture Decision Records, we created an ADR repository in Github and included a template for engineers to follow. This is a slimmed down version of what is included in our template:

Making architectural decisions at One Medical is intended to be a living process that any team member can contribute to, in order to help bring visibility, shared context, and, ultimately, to make the best possible decisions for the given scenario.

We decided to create one centralized Github repository which would be accessible across the organization, rather than documenting team-specific architecture decisions in separate repositories. This decision helped encourage cross-team collaboration and knowledge sharing to help break down silos across teams.

ADR Process

The initial process for creating an ADR was as follows:

1. Identify an architecture-related problem that needs solving
2. Fill out the Architecture Decision Record template in the One Medical Github ADR repository
3. Open a Pull Request and solicit feedback from key stakeholders
4. Once you have approval from 3 reviewers, merge the pull request
5. Your architecture decision is now documented for the entire technology team to see

We saw initial 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 a lot of good back-and-forth discussion, but decisions weren’t being finalized.

Check out Part 2 of this series: Troubleshooting Decision Records and follow One Medical Technology for more upcoming posts from our technology team!