202204021218 Architecture Decision Records

An Architecture Decision Record (ADR) is a document that captures a decision, including the context of how the decision was made and the consequences of adopting the decision.¹

While the name implies that these would be used for mainly architecture level decisions, many people advocate for using them for nearly any decision, no matter how mundane.¹² The purpose of recording as much as possible is to facilitate the 202110231449 Externalization of knowledge for software projects and product organizations. (202110231440 Knowledge is the backbone of a product organization)

ADRs are beneficial because they enable persistence and transfer of knowledge. They’re a great example of the 202110231445 The SECI model of organizational knowledge in action. They take 202110231457 Tacit knowledge and transform it into 202110231459 Explicit knowledge

ADRs can be used proactively to propose changes, or retroactively to record decisions that were already made.

My experience with ADRs has been split across two levels of use.

1. Organization-wide — Valuable to an extent, but can be used poorly to push things that shouldn’t be approved under the guise of seeking wide consensus. The important thing for these to work are having good, competent coworkers and/or to have people who are not afraid to actively dissent in a widely public forum. They can be an invitation for people to engage in costly bike-shedding or an indispensable log of the collective mind of a group. Which side of this your group falls on is hard to tell and requires some radical candor to identify.
2. Project specific — Always valuable. Even in the divergent scenarios above where people are making choices they shouldn’t. A project specific ADR trail allows the tracing, discussion, and possible reversal of these decisions.

ADR Template

Note: An ADR can refer to the record of all individual decisions or a specific decision. There can be some confusion around this, but typically it’s inconsequential.

The typical format for an ADR log would be something like this

decisions
├─ 0001-use-adrs.md
├─ 0002-use-typescript.md
└─ 0003-add-caching-support.md

An individual ADR follows some sort of template. One example of such a template is

# 0000 - ADR Template

- Status:
- Deciders:
- Date:

## Context and Problem Statement

A few sentences about the context of this decision. What challenge are we facing? What problem do we have? What situation are we in?

## Decision Drivers

- {driver 1, e.g., a force, facing concern, ...}
- {driver 2, e.g., a force, facing concern, ...}
- ...

## Considered Options

- {option 1}
- {option 2}
- ...

## Decision Outcome

Chosen option: "{option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | ... | comes out best (see below)}.

### Positive Consequences

- {e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...}
- ...

### Negative Consequences

- {e.g., compromising quality attribute, follow-up decisions required, ...}
- ...

## Pros and Cons of the Options <!-- optional -->

### {option 1}

{option 1 description | discussion}

- Good, because {argument a}
- Good, because {argument b}
- Bad, because {argument c}
- ...

### {option 2}

{option 2 description | discussion}

- Good, because {argument a}
- Good, because {argument b}
- Bad, because {argument c}
- ...

## Links <!-- optional -->

- {Link type} {Link to ADR} <!-- example: Refined by [ADR-0005](0005-example.md) -->
- ...