Skip to content

Use Markdown Architectural Decision Records

This ADR was inspired by https://adr.github.io/madr/decisions/0000-use-markdown-architectural-decision-records.html.

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

  • Michael Nygard's template — The first incarnation of the term "ADR"
  • MADR 4.0.0 — The Markdown Architectural Decision Records
  • Formless – No conventions for file format and structure

Decision Outcome

Chosen option: "MADR 4.0.0", because

  • Recommended by adrs to use for new projects
  • Metadata can be captured via YAML frontmatter
  • The MADR project is maintained
  • MADR has more sections which aligns more with what we need

Consequences

Need a still maintained ADR tool to facilitate easy creation and maintenance of decisions.

For an ADR tool, see adrs which supports MADR.