1. Use a Lean Markdown ADR Format

• Status: accepted
• Date: 2026-01-05
• Deciders: Jannik Alexander, Stefan Bente, Daniel Köllgen (governance board)

Context

We want to record the architectural decisions of the MSD, including the many decisions the governance board has made since 2024 that exist only in meeting notes. Previous projects have shown that scattered documentation causes confusion, so ADRs must live in the central Hugo documentation.

Writing ADRs is cumbersome, and a format that asks too much is not used. Most of our decisions are made by a three-person board and recorded after the fact, often while the code already exists. The format must therefore capture decisions quickly, state rules clearly, and show where decision and code still differ.

Decision

• ADRs MUST be written in Markdown in content/docs/architecture/adr/, one file per decision, named NNNN-kebab-title.md.
• ADRs SHOULD use the template.
• The template is based on MADR, slimmed down to: Context, Decision, Alternatives, Consequences, and optional Open Questions, Current State and Links.
• Rules in an ADR MUST use the following wording:
  • MUST — mandatory. Deviations need board approval; otherwise the architecture is non-conformant.
  • SHOULD — strong recommendation. Deviations are allowed if justified and documented.
  • WILL — a committed future action; describes intent, not an immediate constraint.
• An ADR’s status is proposed until the board accepts it, then accepted. A replaced ADR is marked superseded by the new one; it is not deleted.
• Architectural Significance defines when a decision needs an ADR.

Alternatives

• MADR 2.1.0 as is — our first choice. Rejected because it repeats each option up to three times (options, pros and cons, consequences), carries instructions that must be deleted from every copy, and has no place for open questions or deviations in the code.
• Michael Nygard’s template — rejected because it has few fields for weighing options.
• Y-statements — rejected because condensing a decision into one sentence loses the reasoning new team members need.
• No format — rejected because decisions become hard to find; the board decided several questions more than once for this reason.

Consequences

• Good: an ADR can be written in under an hour, which makes documenting the backlog of board decisions realistic.
• Good: open questions and deviations are visible instead of hidden in meeting notes.
• Bad: one-line alternatives argue less thoroughly than a full pros-and-cons list. For contested decisions, authors MAY add one.