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 Recordsadr.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.