How does the MADR (Markdown Any Decision Records) template differ from Michael Nygard's original four-section ADR template, and when would you choose each?

## Baseline: Nygard's template Michael Nygard's 2011 post "Documenting Architecture Decisions" proposed the minimum viable record: ``` Title ## Status Proposed | Accepted | Deprecated | Superseded by … ## Context the forces at play, stated neutrally ## Decision "We will …" ## Consequences what becomes true afterwards, good and bad ``` Its virtue is that it can be written in fifteen minutes and read in two. Its gap: nothing in the structure *asks* you what else you considered or what criteria you used. Disciplined authors put that in Context or Consequences prose; undisciplined ones omit it, and the record degrades into "we chose X". ## What MADR adds MADR is a community template maintained as an open-source project (`adr.github.io` / the MADR repository). The acronym originally stood for *Markdown Architectural Decision Records*; from version 3 it was rebranded *Markdown Any Decision Records*, acknowledging that the format works for any consequential decision, not only architectural ones. Its structure (3.x) is roughly: ```markdown --- status: accepted date: 2026-02-11 decision-makers: platform team consulted: data team, security informed: all engineering --- # Short title of the solved problem and solution ## Context and Problem Statement ## Decision Drivers ## Considered Options ## Decision Outcome ### Consequences (Good, Bad, Neutral) ### Confirmation (how we verify the decision is followed) ## Pros and Cons of the Options ## More Information ``` The meaningful differences from Nygard: **1. Machine-readable metadata.** Status, date, deciders and the consulted/informed lists live in YAML front matter rather than prose. This makes the log indexable and publishable by generators, and it records *who* decided — a governance fact Nygard's template leaves implicit. **2. Decision Drivers as a first-class section.** These are the criteria the options are judged against: latency budget, operational cost, team familiarity, licence terms, regulatory constraint. Naming them separately does two things — it forces the author to make the evaluation basis explicit, and it makes the criteria reusable for the next similar decision. It also exposes bias: if every driver is "what we already know", that is visible. **3. Considered Options as a required list.** Nygard hopes you mention alternatives; MADR has a heading you must either fill or conspicuously leave empty. This is the single biggest practical difference — the template nudges the behaviour that makes a decision log revisitable. **4. Decision Outcome with explicit justification.** MADR's convention is "Chosen option: *X*, because *…*" — tying the choice back to the named drivers. A justification that cannot reference any driver is a signal the drivers are incomplete. **5. Consequences categorised Good / Bad / Neutral.** Nygard says list consequences; MADR gives the bad ones their own bullet prefix, which measurably reduces the all-benefits record. **6. Confirmation.** A newer MADR section asking *how compliance will be verified* — a code review checklist, an automated architecture test, a fitness function, a lint rule. This is the bridge from documentation to enforcement, and it is absent from Nygard entirely. **7. Pros and Cons of the Options.** An optional deep section giving each candidate its own good/neutral/bad list. This is where MADR's long form earns its keep for genuinely contested decisions — and where it becomes overkill for simple ones. **8. Short form and long form.** MADR explicitly supports dropping to essentially Context + Considered Options + Decision Outcome for small decisions, so adopting MADR does not force ceremony on every record. ## Other templates worth knowing - **Tyree & Akerman (2005)** — the pre-Nygard, heavyweight enterprise form: Issue, Decision, Status, Group, Assumptions, Constraints, Positions, Argument, Implications, Related decisions, Related requirements, Artifacts, Notes. Thorough, and heavy enough that few teams sustain it. - **Y-statements (Zdun et al.)** — a single structured sentence: *In the context of ⟨use case⟩, facing ⟨concern⟩, we decided for ⟨option⟩ and neglected ⟨alternatives⟩, to achieve ⟨quality⟩, accepting ⟨downside⟩.* Excellent as a summary line at the top of a longer record, or for very small decisions. - **ADR-tools / log4brains conventions** — tooling around Nygard-style records: number allocation, supersede linking, index generation, static-site publishing. ## Choosing | Situation | Lean toward | |---|---| | Small team, decisions mostly uncontested, want the habit to stick | **Nygard** — lowest friction, and friction is what kills logs | | Several credible options, cross-team stakeholders, criteria disputed | **MADR long form** — drivers + per-option pros/cons make the reasoning inspectable | | Regulated / audited environment, need who-decided-and-who-was-consulted | **MADR** — front matter and Confirmation carry that | | Existing log already in one format | **Keep it** — mixing formats costs more than either template's shortcomings | | Very small decision inside an otherwise MADR log | **MADR short form**, or a Y-statement | The honest senior answer is that template choice is a second-order concern. A log that exists, is written at decision time, records rejected options with reasons, and is honest about downsides beats a perfectly templated log that nobody maintains. Pick one, write it into ADR-0001, and be consistent — the value comes from the *habit* and the *rationale*, not the headings.