Working at Nava

On our project with the Centers for Medicare & Medicaid Services, we’ve been using Architectural Decision Records (ADRs) to document software decisions — anything that affects architecture, from features to a technology used. ADRs have proved enormously useful — helping us to align teams and keep projects on track — but they’re not a cure-all. We’re sharing some benefits and tactics we’ve found helpful in an effort to help others who would like to start using ADRs or use them in new ways.

Align teams and keep projects moving quickly

First, the big benefit of using ADRs: they help align dozens of people across multiple companies and keep our work on track to successfully deliver projects from day one. Generally, the bigger a technical decision is, the more paralyzing it can be. Using ADRs provides the context for both making a decision and driving the resulting work forward — for everyone involved.

As priorities shift and teams balance meeting short-term expectations with the long-term vision, ADRs help keep everyone on the same page. A complete ADR gives teams from multiple organizations the information to see how and why a decision was made, which stakeholders were responsible for it, and the resulting work. Anytime someone encounters something new in a project, they have the context to understand it. This also, importantly, applies to new team members. When someone joins a project, they can catch up more quickly because they can easily find out how and why decisions were made, without someone else piecing together details to explain it.

Assign one person to write them

There are a few things we’ve learned along the way that help make ADRs easier and more effective. To start, we assign one person to write them. When we give one person the responsibility of writing ADRs, that person tends to champion the implementation of that decision — helping to fully see it through. Often a technical or project lead drafts ADRs because they’re usually responsible for the resulting decisions. But writing ADRs can also be a useful way for someone else to learn about the conceptual underpinnings of a project. Regardless of who writes them, other team members and stakeholders should read and comment on them.

Teams can then move forward in a couple different ways. The person who writes the ADR can do the work. Or they can assign the work to other people. There are pros and cons to both of these approaches — you’ll figure out what works best for your team.

Make sure records are as complete as possible

Whether you’re writing or commenting on an ADR, it may be tempting to rush through it, use shorthand, or assume everyone will remember all the details you talked about. But don’t. Include all of the decision-makers involved and all of the data points, options, and pros and cons that were considered. Knowing, for example, if all the right people signed off on a decision will make it easier for new people or different teams to understand that decision later on. Ultimately, the more complete an ADR is, the more useful and effective it will be in the long-run.

Tie relevant decisions to the big picture goal

While having ADRs helps keep us on track day-to-day, they’re not inherently tied to the larger goal — big picture criteria is not embedded in them. And while not every small decision affects the big picture outcome, many do, and you need to take that into consideration. Our general rule of thumb is the bigger the decision, the more it should reflect the long-term vision. Smaller decisions can have a more tenuous connection. But, if or when a decision from six months ago doesn’t appear to align with the big picture goal, you should be able to go back to the record and understand why it did or didn’t.

Keep learning and improving

This isn’t a perfect system but our process is always a work-in-progress. And for now, ADRs are helping us keep projects on track and teams aligned to deliver projects more quickly. In the interest of continuously learning about and evaluating the tools and processes we use, we’d love to hear from you if you’re using ADRs, and how they’re working (or not!). Reach out to hello@navapbc.com or @NavaPBC.