By the end of the lesson, you can explain what an ADR (architecture decision record) is for, and recognise the elements of a usable decision record.
Why document the decision?
A diagram shows what the system is like, not why it is like that. Half a year later the reasoning is lost, and it is either debated again or unknowingly undone. An ADR records the reasoning of one concrete decision briefly, together with the constraints known at the time of the decision.
The structure of an ADR
There is no mandatory format; a useful record answers these questions:
Situation: under what requirement and constraints is the decision made?
Alternatives: which solutions were considered?
Decision: what was chosen, within what limits?
Consequences: what is gained, what is taken on, what must be checked?
Review: what change could justify a new decision?
"Microservices are scalable" is a general statement. An ADR is more concrete: it names the load profile, the accepted latency and the accepted operating cost.
How does the decision relate to the diagram?
The diagram gives the structure, the ADR gives the reasoning; together they are meaningful. If one changes, the other must be updated as well. The ADR does not replace requirements and quality attributes (1.2); it refers to them.
Comparative evaluation of the decision
It is worth examining the same requirement with several designs and asking the same questions of each: who modifies the data, what happens when a part fails, which change needs two releases, where is compatibility checked. If only the advantages are listed for one design and only the faults for the other, there is no real comparison.
flowchart LR
K["Requirement and constraint"] --> A["Alternatives"]
A --> D["Decision"]
D --> F["Consequences"]
F --> R["Review condition"]
R -.-> K
Common misconceptions
Statement
Clarification
"An ADR is a long plan."
It is a short reasoning of one concrete decision.
"An ADR is an after-the-fact justification of the decision."
It records the alternatives and constraints known at the time of the decision.
"The decision is fixed for ever."
The review condition can explicitly justify a new decision.
In short
An ADR records the reasoning of one concrete decision.
Its content: situation, alternatives, decision, consequences, review.
The diagram shows the structure, the ADR the reason.
The review condition must be checkable.
Review questions
Why is an architecture diagram not enough to preserve a decision?
What are the elements of a usable ADR?
Formulate a checkable review condition for a chosen decision to split a part out.
Recording Architecture Decisions: ADR
Objectives
By the end of the lesson, you can explain what an ADR (architecture decision record) is for, and recognise the elements of a usable decision record.
Why document the decision?
A diagram shows what the system is like, not why it is like that. Half a year later the reasoning is lost, and it is either debated again or unknowingly undone. An ADR records the reasoning of one concrete decision briefly, together with the constraints known at the time of the decision.
The structure of an ADR
There is no mandatory format; a useful record answers these questions:
"Microservices are scalable" is a general statement. An ADR is more concrete: it names the load profile, the accepted latency and the accepted operating cost.
How does the decision relate to the diagram?
The diagram gives the structure, the ADR gives the reasoning; together they are meaningful. If one changes, the other must be updated as well. The ADR does not replace requirements and quality attributes (1.2); it refers to them.
Comparative evaluation of the decision
It is worth examining the same requirement with several designs and asking the same questions of each: who modifies the data, what happens when a part fails, which change needs two releases, where is compatibility checked. If only the advantages are listed for one design and only the faults for the other, there is no real comparison.
Common misconceptions
In short
Review questions
Learning resources