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).
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: A short noun phrase containing the architecture decision
In this section of the ADR we will add a short one- or two-sentence description of the problem.
In this section we will state the architecture decision and provide a detailed justification of the decision.
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.