ZIO’s Blog
Published in

ZIO’s Blog

The Markdown ADR (MADR) Template Explained and Distilled

The Markdown Any Decision Record (MADR) Template turns five today, and its Version 3.0 was released recently. MADR stems from documenting architectural decisions and used to be named “Markdown Architectural Decision Records”; time told that it can be used to document any decision. This post explains the MADR template and its rationale, identifies its essential parts and introduces two emerging tool prototypes.

The MADR template evolved from previous ADR templates such as Michael Nygard’s ADR proposal in the Cognitect blog and my Y-statements. Core parts of previous templates include context, decision and consequences; supplemental parts include status, decision drivers, options with their pros and cons and more information.

Version 3.0 of MADR introduced additional, optional metadata and a “Validation” section. The two sections recording positive and negative “Consequences” were merged to ease copy-paste from the options part. The community appreciates MADR with 1.000 stars on GitHub.

Let’s introduce the three TLAs AD, ASR and ADR.

The ADR website defines Architectural Decisions (ADs) as this:

“An Architectural Decision (AD) is a justified software design choice addressing a functional or non-functional requirement that is architecturally significant.”

With architectural significance being characterized as:

“An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality.” [1]

An Architectural Decision and a decision log then are:

“An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log.”

All these concepts originate from Architectural Knowledge Management (AKM); ADRs capture design decision rationale. That said, the usage of ADRs can be extended to justify and keep track of other decisions, as motivated in the post “ADR = Any Decision Record? Architecture, Design and Beyond”.

The main contribution of the MADR project and repository is its annotated MADR template (or M-ADR template). The repository provides pointers to tools and background information as well.

The structure of the full template follows the decision identification, evaluation, making, enforcement journey that a single AD typically goes through. It is inspired by previous templates. The template sections are named as follows:

Full MADR Template: Up to 10 Elements

Let’s investigate the template sections. Note that the template uses {this font} for content placeholders.

Title. The title assigns a {name} to the AD so that it can be identified and searched for easily. Ideally, it should convey the essence of the problem solved and the solution chosen.

Metadata. The metadata elements are:

  • status: {proposed | rejected | accepted | deprecated | superseded by }
  • date: {YYYY-MM-DD} when the decision was last updated
  • deciders: lists everyone involved in the decision
  • consulted: lists everyone whose opinions are sought and with whom there is a two-way communication (such as subject matter experts)
  • informed: lists everyone who is kept up-to-date on progress in one-way communication.

These five elements are optional; they can be filled out or removed.

Context and Problem Statement. Describes the context and problem statement in a few sentences. One may want to articulate the problem in form of a question or provide an illustrative story that invites to a conversation. Links to collaboration boards or issue management systems can go here too.

Decision Drivers. Desired qualities, forces, faced concerns are identified here:

- {decision driver n}

Considered Options. This section lists the alternatives (or choices) investigated:

- {title/name of option n}

The template recommends listing the chosen option first (as a project-wide convention). One needs to make sure to list options that can solve the given problem in the given context (as documented in Section “Context and Problem Statement”). They should do so on the same level of abstraction; a mistake we have seen in practice is that a technology is compared with a product, or an architectural style with a protocol specification and its implementations. Pseudo-alternatives sometimes can be found too, but do not help.

Chosen Option. Here, the chosen option is referred to by its title. A justification should be given as well:{name of option 1} because {justification}. Some examples of justifications are: it is the only option that meets a certain k.o. criterion/decision driver; it resolves a particular force; it comes out best when comparing options. See this post for more valid arguments.

Consequences. This section discusses how problem and solution space look like after the decision is made (and enforced).

Positive and negative consequences are listed as “Good, because …” and “Bad, because …”, respectively. An example for a positive consequence is an improvement of a desired quality. A negative consequence might be extra effort or risk during implementation.

Validation. This optional section describes how the implementation of/compliance with the ADR is evaluated (aka enforced), for instance by way of a review or a test. See “A Definition of Done for Architectural Decision Making” for related hints.

Pros and Cons of the Options. Here, the alternatives that address the problem can be explained and analyzed more thoroughly.

The template advises to provide an example or a description of the option. Then, “Good” and “Bad” options properties are asked for. For noteworthy “Neutral” arguments, the template suggests the form

Neutral (w.r.t.), because {argument}.

More Information. Here, one might want to provide additional evidence for the decision outcome (possibly including assumptions made) and/or document the team agreement on the decision (including the confidence level) and/or define how this decision should be realized and when it should be re-visited (the optional “Validation” section may also cover this aspect). Links to other decisions and resources might appear in this section as well.

Too much for your taste? Many sections are optional. We see five elements as the essence of an ADR:

Minimal MADR Template: Five Elements

This core is quite close to Michael Nygard’s ADR proposal from 2011 [2].

If you want to reduce even further (which MADR does not recommend), simply state the chosen option and explain why you picked it in a short single sentence.

Let’s decide for one of three options for logical system decomposition (yes, there are more):

You might want to copy-paste this MADR text into your preferred Markdown tool, for instance to render it.

One can create and edit MADRs without having to install any software. The template can be populated in any text editor, and many people use Markdown extensions/add-ins in their IDEs to capture them. However, the community demanded some more support. Some light tools evolved in response. We feature two such tools briefly here, ADR Manager (VS Code) and ADR Manager (Git Hub).

ADR Manager (VS Code) is a Visual Studio Code Plugin, resulting from Steve Chen’s bachelor thesis project at the University of Stuttgart. It supports two modes, basic and professional, and is organized by template sections (such as Decision Outcome):

ADR Manager (Visual Studio Code edition)

The second tool, ADR Manager, is a Web application connecting to a GitHub repository to render all ADRs. It also supports create, read, update, delete operations on ADRs in its editor:

ADR Manager (Git Hub edition)

This application was developed by Daniel Abajirov, Katrin Bauer and Manuel Merkel in a student research project, also at the University of Stuttgart.

At present, both tools work with Version 2.1.2 of the MADR template and expect any existing ADR files to be formatted accordingly. They create (M-)ADRs in this format as well.

Several more tools are listed at https://adr.github.io/madr/tooling.html.

ADRs help you keep CALM because they ease AD making and capturing:

  • Collaborative content creation is enabled.
  • Accountability is supported and unnecessary reconsideration of issues avoided.
  • Learning opportunities are provided, both for newcomers and for the experienced.
  • Management likes them too because it is used to making and executing decisions.

Compared to some Wiki markup languages or proprietary document formats, Markdown has many advantages. As plain text, Markdown is version control- and collaboration-friendly [3]. By design, it forces you to focus on your message (here: ADR content) and logical text flow rather than presentation (page breaks, text formatting and so on) while writing. Tools such as HTML renderers are available, but not mandatory to use [4].

Architectural decision capturing has become an essential practice on agile and any other projects [5]. The MADR template and tools make it very easy to get going. 1000 stargazers can’t be (too) wrong, can they? 😇

In general, one is free to revise the MADR template and adjust optional/required parts according to project/product context and development culture/practices. We recommend doing so early if at all (tools cannot be expected to work with custom versions). Stick to what you have decided for.

Thanks for reading and trying MADR out… as always, feedback and contributions are very welcome! Issues and pull requests in the MADR GitHub repository are good ways to reach us.

- Olaf Zimmermann (with Oliver Kopp, MADR project lead and template co-creator)

PS: If you liked this story, you may want to subscribe to receive notifications about new ones. And/or clap for it 👏

PPS: Chapter 3 of “Patterns for API Design” in the Addison Wesley Signature Series at Pearson features six AD narratives guiding through the conceptual level of API design. The narratives contain 29 recurring decisions with options and criteria. Learn more.

Acknowledgement. Justus Bogner reviewed an intermediate draft of this post and supervised the student projects yielding the two ADR Manager tools.

  1. Usually “measurable effect” is insufficient to decide on significance of a design issue. In response, the blog post “Architectural Significance Criteria and Some Core Decisions Required” proposes 5+2 criteria for “Architectural Significance”: business value/risk, stakeholder concern, quality level, external dependencies, cross-cutting, first-of-a-kind, past troublemaker.
  2. Michael Nygard’s ADR format is not the initial/first one ever created (see here for evidence), but a very visible and well adopted one.
  3. Think git, Gitlab, GitHub with features such as auto-merge, history, release management, CI/CD pipes and so on.
  4. You might want to check out the universal document converter pandoc.
  5. See how Michael Keeling presents the relation in this IEEE Software column.

Originally published at https://ozimmer.ch on November 22, 2022.



The posts in this blog take three different views on software architecture: practicing architect, pattern enthusiast, and software engineering researcher.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Doc SoC

Architectural Decision Maker, Domain-Driven Designer, Serviceorienteer. Author of "Patterns for API Design" and "Design Practice Reference", creator of MDSL