diff --git a/docs/adr/0000-use-markdown-architectural-decision-records.md b/docs/adr/0000-use-markdown-architectural-decision-records.md new file mode 100644 index 00000000..269a626b --- /dev/null +++ b/docs/adr/0000-use-markdown-architectural-decision-records.md @@ -0,0 +1,35 @@ +# Use Markdown Architectural Decision Records + +## Context and Problem Statement + +We want to record architectural 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 + +* [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown + Architectural Decision Records +* [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 + +* Formless – No conventions for file format and structure + +## Decision Outcome + +Chosen option: "MADR 4.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"](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.