Architectural Decision Records
excerpt from "Software Architecture: The Hard Parts"
One of the most effective ways of documenting architecture decisions is through Architectural Decision Records (ADRs).
Architectural Decision Records
adr.github.io
An ADR consists of a short text file (usually one or two pages long) describing a specific architecture decision.
While ADRs can be writen in plain text, they are usually written in some sort of document format, like Markdown.
ADR format:
ADR: A short noun phrase containing the architecture decision
Context
In this section of the ADR we will add a short one- or two-sentence description of the problem.
Decision
In this section we will state the architecture decision and provide a detailed justification of the decision.
Consequences
In this section of the ADR we will describe any consequences after the decision is applied, and also discuss the trade-offs that were considered.
Copy link