ADR Templates

The following UML class diagram shows that many templates for ADR capturing exist, including (but not limited to) MADR, Nygardian ADRs, and Y-Statements:

classDiagram
  direction TB
  class ADR {
    <<abstract>>
  }
  ADR <|-- MADR
  ADR <|-- NygardADR
  ADR <|-- Y-Statement
  ADR <|-- OtherADRTemplate

Markdown Architectural Decision Records (MADR)

MADR is about architectural decisions that matter ([ˈmæɾɚ]). The project provides a full and a minimal template, both of which now come in an annotated and a bare format. Rationale for this decision is available here.

We think that the considered options with their pros and cons are crucial to understand the reasons for choosing a particular design. Therefore, the Markdown Architectural Decision Records (MADR) project in this organization includes such tradeoff analysis information. It also suggests metadata such as decision makers and confirmation in addition to decision status.

Nygard ADR

An ADR consists of title, status, context, decision, and consequences according to “Documenting Architecture Decisions” by @mtnygard.

The blog post from 2011 that suggests this structure is here and a Markdown rendering of it is available here.

Y-Statement

In short, the Y-statement is as follows:

In the context of <use case/user story>, facing <concern> we decided for <option> to achieve <quality>, accepting <downside>.

The long form of it is as follows (extra section “because”):

In the context of <use case/user story>, facing <concern>, we decided for <option> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside/undesired consequences>, because <additional rationale>.

cards42 has adopted the Y-statement template in its German ADR card; the English version is similar, but adds state information. Finally, you can find more explanations and examples on Medium: Y-Statements - A Light Template for Architectural Decision Capturing.

Other ADR templates

Numerous other ADR formats exist, many of which are also featured in @joelparkerhenderson’s GitHub repository.

The template for ISO/IEC/IEEE 42010:2011, the international standard for architecture descriptions of systems and software emgineering, suggests nine information items for ADRs its Appendix A. It also identifies areas to consider when identifying key decisions.