-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
It's a simple and effective way to write quick decision documents
- Loading branch information
Showing
1 changed file
with
35 additions
and
0 deletions.
There are no files selected for viewing
35 changes: 35 additions & 0 deletions
35
docs/adr/0000-use-markdown-architectural-decision-records.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
<https://github.com/joelparkerhenderson/architecture_decision_record> | ||
* 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. |