0001-use-markdown-architectural-decision-records.md

Use Markdown Architectural Decision Records

Adapted from MADR's similar decision record.

• Status: accepted
• Date: 2020-03-25

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.2 – 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.2", 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.2 is the latest one available when starting to document ADRs.

Positive Consequences

The ADR are more structured. See especially:

• MADR-0002 - Do not use numbers in headings.
• MADR-0005 - Use (unique number and) dashes in filenames.
• MADR-0010 - Support categories (in form of subfolders with local ids).
• See full set of MADR ADRs.

Negative Consequences

• Learning curve will be slightly longer.
• Novice writers might initially force themselves to fill all sections of the template, which is not what is intended.