Part 4: Example and Benefits of adopting the ADR process
This is the fourth post of a four-part blog series about how the One Medical technology team uses Architecture Decision Records.
By Amber Houle and Jeff Ammons
In Part 1, Part 2, and Part 3 of this series, we saw how One Medical adopted new practices to help us formalize and document our process of making decisions about our software architecture. Let’s now look at a concrete example of this process in action within One Medical.
As One Medical started building services outside of the monolith, the services would need to expose IDs that could be referenced by other services (external identifiers). We needed to align on a consistent ID generation approach and format. Jane Doe, an engineer leading the development of one of the first services outside of the monolith, needed a solution.
This led to the perfect use case for an Architecture Decision Record:
We had an architecture problem needing a solution, and someone (Jane in this case) that could naturally take the role of a decision lead.
Jane worked to define the problem, do research and speak with appropriate stakeholders and engineers on potential solutions, which amounted to step 1 in our process: Creating a Proposal. A draft was outlined in Google Docs, and then moved to Github to kick off the review process. Here is an example of the ADR Context and Problem statement as defined in Github:
Once all of the considered options (listed below) as well as pros and cons of each option were outlined in Github, Jane was ready to collect feedback and then finalize the decision by scheduling an in person meeting with the architecture council. This particular architecture council consisted of several senior engineers contributing to microservice development at One Medical.
The architecture council was able to reach consensus during the scheduled meeting on the adoption of UUID v4s for external identifiers in service to service communication. After the members of the architecture council approved the open pull request for the ADR in Github, the PR was merged and an email was sent to the tech team to communicate the outcome of the decision. This is just one of many decisions that have gone through this process at One Medical.
Making architecture decisions in this way has allowed us to more easily onboard new engineers, develop shared context, and reduce time spent repeating conversations around why certain technology decisions were made.
Adopting ADRs has also encouraged a larger subset of the engineering team to contribute to proposing and reviewing architecture decisions at One Medical. Creating an easy-to-follow, consistent and transparent approach for adopting architecture decisions across the org helps promote a “bottom up” approach to delivering high quality software, since engineers of all levels have the opportunity to get involved and propose changes.
If your team is making architecture decisions, but lacking a consistent approach to documenting and adopting these decisions, give Architecture Decision Records a try. If arriving at finalized decisions is meeting friction, consider leveraging our three-step process to balance the speed, transparency, and quality of your decisions, outlined in Part 3 of this blog series:
- Creating a proposal — Use the concept of a decision lead to drive the proposal forward.
- Finalizing the decision — Identify decision makers (in our case Architecture Councils) who will provide the feedback required to finalize the decision.
- Communicating the decision — Present the decision to your technology org to develop shared context and minimize knowledge silos across teams
