Use Markdown Architectural Decision Records

• Status: accepted

• Deciders: devs, devops

• Date: 01.06.2020

Context and Problem Statement

We want to record architectural decisions made in this project. Which format and structure should these records follow?

Considered Options

• MADR 2.1.0 - The Markdown Architectural Decision Records

• Michael Nygard's template - The first incarnation of the term "ADR"

• Sustainable Architectural Decisions - The Y-Statements

• Other templates listed at https://github.com/joelparkerhenderson/architecture_decision_record

• Formless - No conventions for file format and structure

Decision Outcome

Chosen option: "MADR 2.1.0", because

• Implicit assumptions should be made explicit.

  Design documentation is important to enable people understanding the decisions later on.

  See also A rational design process: How and why to fake it.

• The MADR format is lean and fits our development style.

• The MADR structure is comprehensible and facilitates usage & maintenance.

• The MADR project is vivid.

• Version 2.1.0 is the latest one available when starting to document ADRs.