1. Use Markdown Architectural Decision Records
- Status: proposed
- Date: 2026-01-05
Context and Problem Statement
We want to record architectural decisions made in this project. Which format and structure should these records follow?
Decision Drivers
- Low barrier of entry - since the act of documenting is always cumbersome, the format should not burden you any more than it needs to. E.g. we do not necessarily need an 11-Point Document for each and every decision.
- Overview - an ADR should provide a list of considered options and why you chose one of them while discarding others.
- Tool support - there is a strong need to integrate ADRs with our central (hugo based) documentation, as natively as possible. Previous projects have shown that scattering relevant documentation leads to a lot of confusion.
Considered Options
- MADR 2.1.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 2.1.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.
- The MADR project is vivid.
- Version 2.1.0 is the latest one available when starting to document ADRs.
Pros and Cons of the Options
MADR
(This whole Document is an Example)
- Good, because a few mandatory concise fields
- Good, because optional fields provide more information about reasoning and weighing different options
- Good, allows for linking to different ADRs
Y-Statement
In the context of capturing architecture decisions, facing tedious verbosity, scattered documentation and knowledge drain from people leaving the project, we decided to implement ADRs using the MADR template and neglected other formats like Y-Statement, Nygard and similar to achieve a simple, lightweight and modular approach to capturing ADs, accepting the fewer guardrails but more verbosity than y-statement, because our decisions are not overly complex and decided within days-weeks instead of months but still need thorough consideration of multiple options in a structured manner.
- Good, because it results in brief ADRs
- Good, because it allows capturing existing decisions rather quickly
- Bad, because options are not considered in depth
- Bad, because condensing decisions this much requires more thought, not less
- Bad, because it lacks information for future readers that are new to the project
NygardADR
- Bad, few fields for weighing options
- Bad, ambiguous fields might lead to vastly different focal points when making decisions
Links
You can add links via the adr tool e.g.:
adr link 1 Amends 0 "Amended by"
or while creating a new one:
adr new -l "0:Amends:Amended by" Use Markdown Architectural Decision Records.
The other option is to use manual linking like this:
[ADR0001]({{< relref "docs/architecture/adr/0000-empty-adr-template.md" >}}) produces:
ADR0001
Or use normal Markdown links (also supports relative linking): [\<Link Name\>]\(docs/architecture/adr/0000-empty-adr-template.md) - Produces: Link Name