Compare decision-record formats
This table compares the five formats supported by the adr.zone generator. It is not a ranking of products or services—only document shapes.
| Criterion | Nygard | MADR | Y-Statement | Outcome-First | ISO 42010 Companion |
|---|---|---|---|---|---|
| Primary goal | One clear decision, minimal ceremony | Repeatable section layout for search & tooling | Single reviewable sentence + fields | Async decision clarity with preserved reasoning | Connect decision to architecture description (stakeholders, concerns, views) |
| Typical length | Short (≈1–2 pages) | Medium (sections expand with options) | Very short in the Y sentence; fields add detail | Short–medium (top 4 sections very short; lower sections clarify) | Medium–long (explicit scope & traceability) |
| Structure | Status, context, decision, consequences | MADR: YAML meta, drivers, options, outcome + nested consequences/confirmation, per-option pros/cons, more info; or minimal variant | One sentence, then the same content as bullets | Status, outcome, decision, primary tradeoff, why, decision boundaries | System, stakeholders, concerns, view/viewpoint, decision, rationale, impact, traceability |
| Automation & index | By convention; easiest with plain headings | Strong: tooling ecosystem expects MADR sections | Weak; good for human scan, not machine index | Strong: structured fields for search, summary, and agent retrieval | Medium: structured fields, not a standard file format |
| Learning curve | Low | Medium (more sections to learn) | Low (once the sentence pattern is known) | Low–medium (easy to read; authors learn to separate outcome from decision) | Higher (42010 vocabulary) |
| Best when | You want Git-first defaults and fast write | You want linting, indexes, and ADR-Manager-style flows | You need a line for stand-up, release notes, or a PR description | Async review, distributed teams, decisions needing quick alignment | Audits, multi-stakeholder systems, or tying to architecture views |
Which format for which team?
- Nygard — minimal friction, fast to write. Best for teams that want Git-first defaults and low ceremony.
- MADR — structured sections including per-option pros/cons; full or minimal template. Best when you need linting, search, or ADR-Manager-style workflows.
- Y-Statement — a single reviewable sentence. Best for stand-ups, release notes, or PR descriptions where brevity matters.
- Outcome-First — outcome, decision, and tradeoff visible before the reasoning. Best for async teams that need quick alignment or disagreement.
- ISO 42010 Companion — explicit stakeholders, concerns, and views. Best for audits, multi-stakeholder systems, or governance alignment.
For the ISO vocabulary (not the same as “ISO 42010 the ADR file”), see ISO / IEEE 42010 and decision records.
Beyond Markdown files: imports & workflow
Teams rarely stop at a raw .md file. The same decision is often reviewed in Git, indexed in a portal, orsynced to a product that tracks ownership and follow-up. That landscape changes quickly, so this site does not list scores or “winner” products.
Representative classes of tools (with examples you can research yourself):
- CLIs and repo scripts (e.g. Nygard-numbered flows, dotnet-adr) — good when everything stays in the terminal and Git.
- Editor and GitHub-integrated UIs (e.g. form-based ADR managers) — good when non-git experts write ADRs and still merge via PRs.
- Developer portals (e.g. Backstage plugins) — good when you need search across services and a single entry point, still backed by Git.
- Workflow-centric products — any tool that imports or mirrors existing Markdown ADRs can sit beside this model; check whether the source of truth remains a repo you control, and what happens on export.
A living list of specific tools and templates is maintained by the ADR community at adr.github.io/adr-tooling. For more links and background, see our resources page.