Compare decision-record formats
This table compares the four shapes supported by the adr.zone generator. It is not a ranking of products or services—only document shapes.
| Criterion | Nygard | MADR | Y-Statement | ISO 42010–inspired |
|---|---|---|---|---|
| Primary goal | One clear decision, minimal ceremony | Repeatable section layout for search & tooling | Single reviewable sentence + fields | Align decision with 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 | Medium–long (explicit scope & traceability) |
| Structure | Status, context, decision, consequences | Problem, drivers, options, outcome, pros/cons, confirmation, … | One sentence, then the same content as bullets | 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 | Medium: structured fields, not a standard file format |
| Learning curve | Low | Medium (more sections to learn) | Low (once the sentence pattern is known) | 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 | Audits, multi-stakeholder systems, or tying to architecture views |
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.