Skip to main content

Use Markdown Architectural Decision Records

Context and Problem Statement

We want to record architectural decisions made throughout the development of the Vidra project. These decisions often involve trade-offs, alternatives, and rationales that should be clearly documented to help current and future contributors understand the reasoning behind the architecture.

The format and structure of these decision records should be:

  • Easy to write and maintain.
  • Friendly to developers familiar with Markdown and Git-based workflows.
  • Simple enough to not slow down development, but structured enough to be useful in the long term.
  • Supported by tooling where possible.

Considered Options

  • MADR 4.0.0 – Markdown Architectural Decision Records
    A lean, structured Markdown format for documenting decisions, designed to be readable, minimal, and Git-friendly.

  • Sustainable Architectural Decisions – The Y-Statements
    A highly structured format intended to make decisions measurable, but possibly too heavyweight for our needs.

  • Other templates listed at https://github.com/joelparkerhenderson/architecture_decision_record
    Includes various formats with varying degrees of complexity and structure.

  • Formless – No conventions for file format and structure
    Ad-hoc documentation in any form, without a defined standard or naming convention.

Decision Outcome

Chosen option: "MADR 4.0.0", because:

  • It promotes making implicit assumptions explicit, helping future contributors understand the design rationale.
  • It aligns well with our fast-moving and iterative development style.
  • The structure is simple, readable, and easy to review in code reviews or documentation audits.
  • It encourages consistency without being overly restrictive.
  • The project is actively maintained and has supporting tooling, such as the ADR Manager extension for Visual Studio Code.
  • Version 4.0.0 was the latest available when we began documenting our ADRs.

Consequences​

  • Good, because it provides a clear, structured way to document decisions without being overly complex.
  • Bad, because it may require some initial effort to set up and get used to the format.

We believe MADR strikes the right balance between structure and flexibility for Vidra's needs.