Wikis are the default place teams put decisions, and the default place where decisions go unread. The pattern fails so consistently that it's worth designing around it directly: document decisions without a wiki, using tools the team already uses, with stable URLs and queryable structure. The result is documentation that actually gets read.
Why wikis fail decisions
Wikis have unreliable search, weak structure, no integration with daily workflow, and rapidly age. The team writes a decision into the wiki; nobody opens the wiki; the decision is invisible. Add three months and the wiki itself is forgotten.
The fix is not a better wiki. It's choosing a different surface entirely.
Option 1: an ADR folder in the monorepo
For teams with strong code culture, decisions live in the codebase. /docs/adr/0042-postgres-for-billing.md with the four-field format. Searchable via git grep, linked from PRs, reviewed like code.
Strengths: integrates with PR review, never disappears, version controlled. Weakness: non-engineering team members can't easily contribute.
Option 2: a structured database (Notion, Airtable, Linear)
Decisions as records with explicit fields. Tag by surface, by decider, by date. Query by any field. URLs are stable; search is usable.
Strengths: cross-functional contribution, easy filtering, friendly UI. Weakness: depends on continued vendor existence.
Option 3: a dedicated governance tool
For teams that need audit trails, multi-tenant governance, or AI-queryable history, a governance tool is purpose-built. Decisions become first-class records with authority, scope, and rationale.
Strengths: tailored UX, audit-ready, AI-friendly. Weakness: another tool in the stack.
Decide which surface fits your team
Quick decision rubric:
- Engineer-heavy team, code-first culture → ADR folder.
- Cross-functional team, mid-size company → structured database.
- Regulated, large org, audit needs → governance tool.
Any of these beats the wiki. Pick the one that fits your team's existing habits.
Use stable URLs
Every decision needs a URL that doesn't change. URLs that move when the document is renamed are no better than no URL — links rot, references break, the archive becomes unreliable.
Test: pick a decision URL, wait a month, click it. Does it still work? If not, the surface is wrong.
Decisions Without the Wiki Tax
StandIn captures decisions where work happens — Slack, Linear, GitHub — and promotes them into a queryable layer.
See the Workflow →Tag for queryability
Each decision gets at minimum: a surface, a decider, a date, a status (active/superseded). With those four tags, almost any reasonable query can be answered: "decisions about payments in the last quarter," "decisions made by the platform team that are still active," "recent reversals."
Without tags, you're back to keyword search and rough recall.
Promote decisions from where they happen
Decisions are made in Slack, PRs, meetings, RFC comments. The discussion lives there; the record gets promoted to your chosen surface. The promotion is a one-time action — usually within a day of the decision being made.
Trying to make all decisions happen in the documentation surface fails. Let discussion happen where it happens; promote the outcome.
Common failure modes
Failure: starting from scratch. The team has decisions in many places already. Pick the surface, back-fill the last quarter, then start fresh going forward.
Failure: building a custom system. Almost always worse than using an existing tool. The maintenance cost will outlast your patience for it.
Failure: requiring rich formatting. Long-form decisions deter contribution. Four fields, plain text, minimum viable record. Richness can come later.
What to do tomorrow
Pick the surface this week. Move three recent decisions into it as proof of concept. Pin the location in your team channel. The next decision your team makes — promote it to the new surface and link in the discussion thread. Three weeks of consistent practice and the habit settles.
Frequently asked questions
What if our company already standardized on a wiki?
Use the wiki for the things it does well — onboarding docs, runbooks, reference material — and use a different surface for decisions. Wikis aren't bad; they're just bad for decision records.
How do we migrate off a wiki we already have?
Don't migrate; supersede. Start the new surface; back-fill recent decisions; let the wiki fall out of use naturally. Forced migration produces resistance and incomplete moves.
Can AI help index existing decisions?
Some. AI can extract candidate decisions from Slack and PR history. The four-field structuring still needs human judgment — what's a real decision, what's just a preference. Use AI for retrieval; keep humans on classification.
Get async handoff insights in your inbox
One email per week. No spam. Unsubscribe anytime.
Ready to eliminate your daily standup?
Distributed teams use StandIn to start every shift with full context — no standup required. Engineers post a 60-second wrap. The next shift wakes up knowing exactly what to work on.