One is a living page.
One is a fixed record.
They look interchangeable when you are choosing where to put a decision, and they diverge completely eighteen months later when somebody needs to know what you believed at the time. The difference is not features. It is whether the document is allowed to change.
Ask what the team believed in March
Every evaluation should start here, because it is the only question that separates the two. Everything else — search, permissions, editor, templates — both do fine.
The wiki page
Has been edited nine times by five people. The current version describes what the system does now, which is useful and is not what was asked. The reasoning that justified the original choice was tidied away in edit four as out of date.
The decision record
Was written once in March and never touched. It says what was chosen, what was rejected and who objected. If the decision was later reversed, a second record says so and links back — and both are still readable.
What each format is actually good at
| What you need | Wiki page | Decision record |
|---|---|---|
| Answers "what did we believe in March" | — | ✓ |
| Preserves the option you rejected | — | ✓ |
| Immutable once written | — | ✓ |
| Reviewed in the pull request that caused it | — | ✓ |
| Versioned with the code it describes | — | ✓ |
| Readable by a coding agent in the repo | — | ✓ |
| Long-form onboarding narrative | ✓ | — |
| Comfortable for non-engineers to edit | ✓ | — |
| One page that stays current as things change | ✓ | — |
Three rows favour the wiki, and they are real. A living page is the correct home for a narrative that should always describe the present — an onboarding guide, a runbook, a system overview. Freezing those would be a mistake.
Most teams need both, doing different jobs
The failure is not picking wrong. It is using one document type for two jobs with opposite requirements — one that must always be current, and one that must never change.
Wiki for the present
How the system works today, how to run it, how to join the team. Should be edited freely and should always describe now.
Records for the past
What was decided and why, frozen at the moment it was true. Superseded by new records, never overwritten by them.
Neither for the habit
Both formats assume somebody sits down afterwards and writes. That assumption is what fails, in both cases, for the same reason.
Neither format fails. The writing step does.
Worth stating plainly, because choosing between the two is usually a way of avoiding the thing that actually broke.
Almost every abandoned documentation system was abandoned for the same reason, and it is never the template. The decision gets made across fourteen commits, an argument in a review, and an incident channel at two in the morning. By the time anyone could write it down, the work is finished, the context has gone cold, and the next thing is already urgent. Most ADR directories stop at record four. Most wikis go stale in a quarter.
The version that survives is the one nobody has to remember: an agent that reads the work that already happened and writes the record itself, in whichever format you keep. The format debate matters much less than the fact that a record exists at all.
What teams ask before deciding
01Can I just use a wiki page for decisions?+
02What actually makes an ADR different from a wiki page?+
03Do ADRs have to live in the repository?+
04Why do most ADR directories stop at four or five records?+
05Should we migrate our existing wiki?+
06What about Notion or Confluence with AI turned on?+
Keep going
Free ADR generator
Write your first record from a pull request you already merged. No account.
Documentation that keeps the why
The agent that writes the records from the work, so the habit is not yours to keep.
Why agents need the why
An agent that cannot see the reason behind a constraint will refactor it away.
Pick a format in a minute. Fix the habit in an afternoon.
Generate your first decision record from a merged pull request, then decide whether writing the next hundred by hand sounds likely.