30 lines
1.3 KiB
Markdown
30 lines
1.3 KiB
Markdown
---
|
||
parent: Decision Records
|
||
nav_order: 0
|
||
---
|
||
# Use Markdown Any Decision Records
|
||
|
||
## Context and Problem Statement
|
||
|
||
We want to record any decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields.
|
||
Which format and structure should these records follow?
|
||
|
||
## Considered Options
|
||
|
||
* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
|
||
* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-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", 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](https://doi.org/10.1109/TSE.1986.6312940).
|
||
* MADR allows for structured capturing of any decision.
|
||
* The MADR format is lean and fits our development style.
|
||
* The MADR structure is comprehensible and facilitates usage & maintenance.
|
||
* The MADR project is vivid.
|