Use Markdown Architectural Decision Records
Adapted from MADR's similar decision record.
- Status: accepted
- Date: 2023-10-16
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 3.0.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 3.0.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.
- Version 3.0.0 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.