Architecture Decision Record (ADR)

ADRs as a decision-making tool like RFCs

From Wikipedia:

Steve Crocker first introduced the RFC system in 1969 to help record unofficial notes during the creation of the ARPANET. Later, Internet RFCs became established and are used by the Internet Engineering Task Force as official documents of Internet specifications, communications protocols, procedures, and events.

I value the trust and believe that individual contributors should be involved in architectural and high-level technical decision-making. I consider every line of code to be a decision made on behalf of someone else, and having a fast-growing team makes technical decision-making particularly difficult to manage.

ADR is a critical documentation and validation tool to archive your main architecture decisions.

You should use this type of process to:

• enable individual contributors to make decisions for systems they’re responsible for,
• allow experts to have input in decisions,
• manage the risk of decisions made,
• include teammates members without it becoming design by the committee,
• have a snapshot of context for the future,
• be asynchronous,
• work on multiple projects in parallel.

ADR Process

The Architecture Decision Record (ADR) begins with a brief introduction explaining the ADR’s goal. While the introduction section is read first, it should be authored last. Writing the overview allows the author to summarize the ADR’s final content rather than write an introduction without knowing the result.

Idea💡

You should write an ADR if you:

are building something from scratch, new endpoint, component, system, library, application, etc.,

are impacting more than one system or other team members,

are adding a new technical dependency,

are adding or replacing languages or tools to the stack,

are using external services (an external service is outside of the application itself and its system requirements),

are adding new code triggered,

have a new technical idea or topic risen from your technical watching, from the Guilds, from a product feature,

are changing the ADR process itself.

Recruit ADR sponsor 🏅

A sponsor is a seasoned engineer, often a Staff/Principal Eng or Ops, responsible for ensuring the best possible outcome of the ADR process. In particular, this includes:

advocating for the proposed design

guiding the ADR to adhere to existing design and style conventions

guiding the review committee to come to a productive consensus

when approved, ensuring proposed implementation is prioritized and assigned to teams

People need to identify the sponsor before submitting an ADR.

Use the template ✍️

To the same understanding for everyone, it is crucial to use the same template. The following template aims to propose and validate a new ADR.

Status: [WIP | In Review | Approved | Obsolete]

Date: 2021/04/09 12:00 AM (UTC)

Reviewers

• CTO and/or CPO,
• VP Eng, if any,
• Principal Engineers,
• Engineers…

Each of the representative stakeholders must review the ADR before it proceeds to kick-off.

Sign-off by stakeholders requires these to be satisfied:

• the release summary defines which acceptance criteria are in scope,
• engineering and Product Management agree on the target release,
• schedule a meeting with engineering, and design to review the ADR.

Background

The background section aims to provide the reader with helpful context before diving into the problem domain. Provide sufficient details to educate the reader on the problem domain properly. For a reader to understand the content of the ADR, they must first understand the context. That context setting is the goal of the background section. Visual explanations are encouraged if applicable. This context includes describing at a high level the functionality provided to clients (end-users, components, etc.), what OKR does this relate to, or why do we think this project will help the business objective we’re after?

Goals

Product goals should be formalized as “assumptions to be proven,” and we should always ask yourselves, “What is absolutely mandatory to test this assumption?” and do this step first and foremost. Each of the problems should clearly map to the user research problems and the corresponding personas defined below. The personas should be generic versions of the actual interviewed users. Personas could have trouble developing this problem, trouble to operate this problem, or securing this problem.

Technical goals should also include numbers like traffic assumptions, usage, or uptime requirements:

• Provide native user experience to customers,
• Make customer deployment automated,
• Make cluster upgrade automated,
• Ensure customer isolation at the cluster level,
• Integration with company ecosystem,
• …

Non Goals

List all non-goals of the project (not a mandatory section)

Design Overview

Summary of the solution in a paragraph or two.

This should not go too long; it’s meant to paint a quickly and easily accessible picture of what’s being built.

Design Diagram & Details

Diagram of all the binaries, databases, and third-party services that this design touches. Having a visual helps many folks get the high-level picture and understand what’s being impacted more easily.

Considered Alternatives/Trade-offs made

This is a great place for disclaimers on why certain choices are being made, what any negative implications might look like, limitations being taken into account, any technical debt that might earn along the way, and changes that may need to be made future as a result.

Phases

It’s important to deliver fast; you should not think in quarters but steps; each step doesn’t have to last three months! The problem is broken down into phases to enable iterative implementation.

Each phase:

1. Builds value on the previous phase, and therefore, they are defined in sequential order of value. There is no need to define priority as that’s inferred from ordering,
2. It is not considered complete until all of the requirements are fulfilled,
3. Should provide end-to-end value. Even if it can address only the different phases, this should provide value and feel like a new feature/solution.

Some ADRs will only have one phase, which is completely fine.

Submit your ADR 📤

It would be best to launch your new ADR in a public Slack channel or by mailing list where you get the maximum reach. Your implementation of ADRs recommends that proposals remain open for comments for a minimum of two days and a maximum of a week. Still, shorter or longer are allowed depending on the context.

Community members have to:

• provide feedback as soon as possible to allow adequate time for consideration,
• read ADRs thoroughly before providing feedback,
• be civil and constructive (indeed!!).

Validate your ADR ✅

The sponsor will request a review committee meeting no sooner than 2/3 weeks after the ADR is published. The review meeting’s goal is to resolve minor issues; should reach a consensus on major issues beforehand.

Review committees must:

• ensure that substantive items of feedback have been accounted for,
• add their meeting notes as comments on the PR,
• provide reasons for their decisions.

The review committee may approve the ADR, reject it, or require changes before it can be considered.

I’ve found the ADR approach to be a great way to communicate decisions and keep historical context. ADRs didn’t replace the traditional documentation but should complement existing ones to enrich projects with a reference frame.

I hope these insights will be helpful to you. Thanks for reading.