Architecture Decision Records (ADRs)

Helpful now, invaluable later

Architectural decision

Design decisions that address architecturally significant requirements

hard to make and/or costly to change

Taken from: https://en.wikipedia.org/wiki/Architectural_decision

Consider a structural change

How costly will this change be in time, money, and effort?
Does this change add complexity to the system, or simplify it?
Will this change require more changes?
What are the security implications of this change?

Taken from: https://18f.gsa.gov/2021/07/06/architecture_decision_records_helpful_now_invaluable_later/

Discussion

Oral history

PR / issues

Limits of Oral History

Short reach
Time consuming to share
Changes over time

Before long, important details are forgotten

Taken from: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf

Discussion

Documentation?

Oral history

PR / issues

Title Text

Bullet One
Bullet Two
Bullet Three

An ideal documentation

Low barrier to entry
Value-adding, useful
Small, modular documents have at least a chance at being updated

What is the least we can document
and still remain effective?

is it easy to track changes? 🤔

Taken from: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf

Why to track a decision?

Without understanding the motivation behind certain decision, a new person coming on to a project has only two choices:

Blindly accept the decision

Blindly change it

Taken from: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html

Discussion

ADR 🙂

Oral history

PR / issues

ADR

“An architecture decision record is a short text file in a format similar to an Alexandrian pattern that describes a set of forces and a single decision in response to those forces.”

Taken from: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html

Rationale

Architecturally significant change

Decision

Consequences

Status

Context

How would it look?

Title
Context
Design decision
Rationale
Status
Consequences

Taken from: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf

Template

Markdown
Direct language
Brief, 1-2 pages max
Stored with the code (peer review)

# ADR N: Brief Decision Title
Context goes here. Describe the forces at play, including technological, political,
social, and project local. These forces are likely in tension, and should be called
out as such. The language in this section is value-neutral. It is simply describing
facts. Rationale should be self-evident from the context
## Decision
This section describes our response to these forces. It is stated in full sentences,
with active voice. "We will ...“
## Status
choose one: [Proposed | Accepted | Deprecated | Superseded]
if deprecated, include a rationale. If superseded, include a link to the new ADR
## Consequences
Describe the resulting context, after applying the decision. All consequences should
be listed here, not just the "positive" ones. A particular decision may have positive,
negative, and neutral consequences, but all of them affect the team and project in the
future.

Taken from: https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf