Architecture Decision Record - ADR

Document 'Why', not What

Published on Saturday, October 31, 2020
Tools

A Documentation Problem

How often have you wanted to update something you did not understand? Not just the logic behind it, but the reason why someone did something exactly that way? And how many hours/days(/weeks?) it took you to finally conclude that "that stupid piece of code" was actually pretty smart and that was you, who was wrong and has wasted a lot of time?

Documentation is not just about what has been done but also about the motivation behind certain decisions. It is often easy to understand the code, but not the entire logic behind it. Sometimes it is even helpful to understand the process of decision making and how developers came to their conclusions.

So? Document everything?

Maybe...

But, who reads large documentation? Who updates large documentation?

Ok. Small documents... But when to write them? At the start of the project?

But we are agile, many of the architectural decisions will not be defined at the beginning, but during the development...

How to keep up with the constant changes, but remain flexible and up to date?

...

Architecture Decision Record

“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.”
Documenting Architecture Decisions by Michael Nygard

Basic ideas behind ADR:

  • Keep it short and simple
  • We do not have to be strict with the writing style and details - do what works best for you
  • Use text-only format like markdown
  • If necessary, add images or something like PlantUML diagrams
  • Keep up the records of the important decisions at one place - single folder with a format like doc/arch/adr-NNN.md - do not reuse numbers (or use dates YYYY-MM-DD)
  • Each ADR should go through the code review process
  • Keep it in source control, usually with a source code of the project
  • Keep the old ADRs around, even if decisions are reversed, but mark them as superseded

ADR Template

There are many ADR templates, but I like Nygard's simplicity.

# Title

## Status

What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

## Context

What is the issue that we're seeing that is motivating this decision or change?

## Decision

What is the change that we're proposing and/or doing?

## Consequences

What becomes easier or more difficult to do because of this change?

ADR is also great for:

  • Onboarding - new team members can get up to speed much faster
  • Sharing knowledge between teams - Other teams, at their own time, can get up to speed with decisions of their colleagues
  • Training - Peer review, pair, coach

ADR Tools

Do you need special tools? Just use Git and markdown. Of course, you use anything you are comfortable with, Microsoft Word, Google Docs, Wiki, or any project tracking software...

References