Architecture Decision Records
No more, i have no idea why we use this, lets understand really why we made that decision.
Software solutions will be made of multiple decisions, as we progress we will need to understand when a decision is obsoleted.
We use Architecture Decision Records (ADR) to keep this context.
TL;DR;
Architecture Decision Record (ADR)
- An ADR is driven by a change in context (aka we found a problem)
- Captures a decision for something we think is Architecturally signficant
- ADR’s a immutable, where existing ADRs can be obsoleted/replced by new ones
- they are meant to be simple
- there are many templates, find one which suits you
Background
As we build solutions we will make a number of decisions. for example why a database pattern was choosen or an integration technology.
Over time, some projects/products have struggled to recall why they did something. which makes it hard to understand if they should keep a certain technology or pattern.
You may hear the sentance “we have always done this”
Enter in the Decision
An Architecture Decision Record (ADR), is meant to capture the reason for a choice agsinst a problem (aka a descision).
As we record the context of why a decision was made. This allows us to review past decisions and make new informed decisions to retain or obsolete them as the context changes.
Effectively we are removing the “why do we do this?” “cos its what we have always does it.” scenario
Structure of a Decision
ADR’s in essence need to capture the context/problem and the decision/solution.
There are a number of templates out there that people use (which annotate the infromation being capture at the point in time) here is one - Simple ADR Template
I like to capture the following
| Description | Simple ADR Template | |
|---|---|---|
| Title | Meaningful title for the decision | ✔️ |
| Context/Problem | Description of the issue, what is the context | ✔️ |
| Status | What the status is: ✔️ approved, ❌ rejected, ⭕️ obsoleted |
✔️ |
| Obsoletes | List of decisions this decision obsoletes | |
| Obsoleted By | A decision this decision obsoleted by | |
| Considered Options | what was considered while deciding | |
| Spikes | links to spikes you may have carried out to validate this decision | |
| Decision | what is the change being proposed | ✔️ |
| Consequenses | what are the impacts (what is made easier and harder) due to the change/decision | ✔️ |
What you capture depends one what you find to be important.
When to capture a Decision?
Decisions are made when there is a change in context, and we what to capture the information for future reference.
as they are are events, we treat them as immutable. We can obsolete a decision by creating a new ADR, normally this would mean there is a change in context (i.e. a constraint has change like resource, money, knowledge, technology, timing etc).
