Wiki or Docs? Choosing the Right Home for Team Knowledge

"Where should this go?" is the question that quietly determines whether a team's knowledge survives. A new runbook, a project brief, meeting notes, the vacation policy — someone finishes writing and hovers over two destinations: the wiki, or a doc. Most teams never decide the rule, so every writer decides alone, and eighteen months later half the knowledge lives in each place, nobody knows which half, and every search is two searches.

The wiki-versus-docs question is not a tooling preference. Wikis and docs are different instruments with different physics — different editing models, different structures, different decay curves — and each is genuinely better at a class of content the other handles badly. This post breaks down what each format is actually good at, settles the markdown-versus-blocks question with tradeoffs instead of taste, names the failure modes of going all-in on either, and lays out the hybrid model that most teams should run, including the promotion rule that makes it work.

What we mean by each

Terminology first, because tools blur it.

A wiki is a curated collection of interlinked reference pages: flat-ish structure, heavy internal linking, pages meant to be the answer on their topic. One page per topic, edited in place forever, with history. The archetype is Wikipedia; the workplace versions are markdown knowledge bases and classic tools like MediaWiki or Confluence in its original spirit. Wikis assume an audience of readers who did not write the page.

Docs are free-form documents in a flexible editor: rich blocks, nesting, low ceremony. A doc is born from a person or a moment — a project brief, a proposal, meeting notes, a draft. The archetypes are Google Docs and Notion pages. Docs assume an audience of collaborators close to the work.

The formats differ on five axes that matter:

Axis	Wiki	Docs
Unit of organization	Topic ("Deployment process")	Artifact ("Q3 launch plan")
Lifecycle	Evergreen, edited in place	Created, used, superseded
Structure	Curated tree + dense links	Organic nesting, grows by accretion
Authorship	Communal; page outlives author	Owned; doc belongs to its moment
Truth model	This page IS the answer	This doc is A snapshot

That last row is the important one. A wiki page called "Refund policy" makes a promise: what it says is what is true. A doc called "Refund policy discussion — March" makes no such promise. Readers can feel the difference, and the whole game is making sure content sits in the container whose promise it can keep.

What wikis are actually good at

Reference knowledge with one right answer. Policies, how-tos, runbooks, glossaries, system overviews. Content where a reader needs the answer, not a document trail. The one-page-per-topic constraint is a feature: it forces consolidation, so search returns one authoritative hit instead of six drafts.

Surviving authors. Wiki pages are communally owned by design — editing someone else's page is the normal act, not an intrusion. That makes wikis resistant to the biggest knowledge-killer there is: the author leaving. A doc dies with its owner's relevance; a wiki page just gets its next editor.

Link density. Wikis are built around internal links — every mention of another topic links to its page. Dense linking is what makes reference material navigable in practice (readers arrive mid-graph from search and orient by links), and wiki culture produces it naturally, where docs culture produces link deserts.

Trust through curation. Because a wiki is smaller and edited-in-place, it can plausibly be maintained — owners, review dates, staleness sweeps. Readers learn they can trust it, and trust is the entire asset. Nobody even attempts to maintain a docs area of four thousand accreted pages; everyone knows most of it is sediment.

The wiki's weakness is exactly its strength inverted: ceremony. Creating a wiki page implies claiming a topic, finding its place in the tree, writing for strangers. That is friction, and friction means the wiki never captures the fast-moving 80% of team writing — briefs, notes, drafts, plans. Teams that mandate "everything goes in the wiki" get one of two outcomes: the wiki fills with meeting notes and stops being trustworthy reference, or people route around it back to scattered docs. Usually both.

What docs are actually good at

Thinking and collaborating. Proposals, briefs, specs, agendas, drafts — writing whose purpose is to develop an idea with a small group, not to archive a settled one. The doc editor's richness serves this: comments for argument, embeds and tables for evidence, blocks for restructuring mid-thought. Making someone draft a proposal in a reference wiki is like making someone brainstorm on letterhead.

Zero-friction capture. A doc costs nothing to create, which is why docs capture the vast majority of what teams actually write down. Meeting notes exist because the container was one click away. Whatever knowledge system you design, the raw material enters through docs, and a system that fights this loses.

Structured-but-informal hierarchy. Nested docs mirror how projects actually unfold: a project page with children for brief, decisions, notes, and retro. The hierarchy is private-ish scaffolding for the working group — perfect for the work, and nearly useless to an outsider two years later, which is fine, because outsiders-later is the wiki's job.

Rich content. Embedded tables, task lists, toggles, images, databases-in-pages. For working documents this expressiveness earns its keep daily.

The docs weakness is the mirror image: docs accrete. Nothing is ever consolidated, nothing supersedes anything explicitly, and search over a docs pile returns five partially-true snapshots from different eras with no way to tell which one still holds. An all-docs knowledge system is a hoard: everything was kept, so nothing can be found and nothing can be trusted. The failure arrives slowly — the pile is genuinely fine for a year — and then a departure or a compliance question reveals that the team's "knowledge base" is an unranked archive of moments.

Markdown vs blocks: the editor question underneath

Wiki-versus-docs usually smuggles in a second debate: plain markdown versus rich block editors. This one also resolves by content type rather than taste.

Markdown's case. Portability — plain text moves between tools without loss, which matters for content meant to outlive tool choices (exactly the wiki's content). Diffability — markdown edit histories are readable line diffs, which supports the review-and-maintain workflow reference content needs. Speed and constraint — headings, lists, links, tables, code blocks are the whole vocabulary, which keeps authors writing instead of formatting, and keeps a hundred authors' pages looking uniform. Engineers' comfort with it is a bonus, not the argument. The full portability case is in markdown for teams.

Blocks' case. Expressiveness — toggles, embeds, columns, inline databases, callouts. WYSIWYG accessibility for teammates who see |---|---| table syntax as a wall. Restructuring — dragging blocks around during active thinking beats cut-and-paste. For collaborative working documents, blocks are simply better instruments.

Notice the alignment: markdown's virtues (portable, diffable, uniform, constraint-driven) are maintenance virtues, and maintenance is the wiki's defining activity. Blocks' virtues (expressive, malleable, approachable) are composition virtues, and composition is the docs' defining activity. The editor debate dissolves once the container question is settled: markdown wikis, block docs. Tools that force one editor for both jobs force a compromise somewhere — usually rich-editor wikis whose pages drift into inconsistent formatting no one can diff, or markdown-everything setups that exclude half the company from writing.

The hybrid model: two containers, one rule

Nearly every team past about ten people should run both containers with an explicit contract. The model has three parts.

Part 1: The routing rule

One sentence, published where everyone sees it:

Docs are where we work; the wiki is what we know. Working writing (briefs, notes, proposals, drafts, project scaffolding) starts in Docs. Settled reference (policies, how-tos, runbooks, definitions, decisions) lives in the wiki. If a reader six months from now would need it to be true, it belongs in the wiki.

The test at the end does the real work. Meeting notes: a record of a moment, not a promise of truth — Docs. The refund policy: must be true — wiki. A project brief: snapshot — Docs. The deployment runbook: must be true — wiki. Writers stop hovering, and readers gain the reciprocal rule for free: to know what is true, check the wiki; to see how we got here, check the docs. Search results become interpretable — a wiki hit is an answer, a docs hit is history.

For teams that want more than the one-sentence rule, here is the routing table for the content types that generate the most hovering:

Content	Container	Notes
Vacation / expense / security policy	Wiki	Must be true; one page per policy
Runbooks and on-call procedures	Wiki	Must be true at 3 a.m.; review dates mandatory
How-to guides ("how to deploy," "how to file expenses")	Wiki	Titled as the question people will search
Glossary and system overviews	Wiki	Dense-link them from everywhere
Decision records	Wiki (log or page)	Link to the proposal doc for full reasoning
Project briefs and specs	Docs	Snapshot of intent; supersede freely
Meeting notes	Docs	Record of a moment; promote decisions out
Proposals and RFCs	Docs	Argument lives here; verdict gets promoted
Drafts of anything	Docs	Including drafts of future wiki pages
Research notes, competitive analysis	Docs	Date-stamped snapshots by nature
Onboarding guide	Wiki	Highest-traffic truth you own
Team charter / working agreements	Wiki	Small, stable, communally edited
OKRs and quarterly plans	Docs	Time-boxed by definition; link from a wiki index if needed

Two entries surprise people. Decision records go to the wiki side despite being born in a docs-shaped process, because their whole value is being findable and true later — the proposal doc holds the debate, the wiki holds the verdict. And the onboarding guide is wiki content even though it feels like a document, because a new hire needs it to be true, and it will outlive every author it has.

Part 2: The promotion ritual

The hybrid model's moving part, and the thing most teams miss: knowledge is born in docs and must be promoted to the wiki, because settled knowledge does not file itself.

Promotion is a small, explicit act: when a doc produces something durable — a decision, a process that will repeat, an answer that will be asked again — someone distills it into the relevant wiki page (usually a paragraph, not a transplant) and links back to the source doc for the full context. The wiki page carries the durable claim; the doc keeps the reasoning trail.

Make promotion a checklist line in the rituals where knowledge settles, so it happens without heroics:

• Project close: "What here belongs in the wiki?" — process learnings, new system pages, updated runbooks.
• Decision made: the decision record gets a wiki entry (or the wiki's decision log gets a row) linking to the proposal doc.
• Retro or post-mortem: one owner files the durable lessons.
• Quarterly docs sweep: 30 minutes; scan the quarter's most-touched docs for unpromoted knowledge, then let the docs sink into archive naturally. Docs are allowed to rot — that is the point of having a container where rot is safe.

Teams that skip promotion end up with a pristine, thin wiki and all the real knowledge trapped in docs — the sorted-hoard failure. Teams that over-promote (transplanting whole docs) end up with a wiki full of snapshots wearing reference clothing. The distillation step — a paragraph in the topic page, link to the source — is the calibration.

Part 3: Ownership asymmetry

The two containers get different maintenance regimes, on purpose. Wiki pages get owners, review dates, and staleness sweeps — the full regime from the knowledge management guide, affordable precisely because promotion keeps the wiki small. Docs get almost nothing: an archive-by-default attitude, maybe a yearly cleanup of top-level clutter. Spending maintenance effort on docs is spending it where trust was never promised; spend it all on the container that made the promise.

Promotion in practice: one decision's path

Concrete version. A product team spends two weeks deciding whether to build annual billing. The work happens in Docs: a proposal ("Annual billing — proposal, April") with pricing math, two comment threads arguing about proration, a meeting-notes child page, and a revised draft. On Thursday the team decides: yes, with proration credited monthly.

Without promotion, that is where it ends. In September, a support lead asks in chat, "do we prorate annual downgrades?" Someone half-remembers the April doc, searches, finds the first draft — which proposed the opposite — and confidently answers wrong.

With promotion, Thursday's decider spends six minutes: adds a row to the wiki's decision log ("2026-04: Annual billing ships with monthly-credited proration — context →" linking to the proposal doc), and updates the "Billing" wiki page's proration section to state the new behavior as fact. The proposal doc gets a banner line at the top: "Decided 2026-04 — see Billing wiki page for current behavior." Now September's search hits the wiki page first, the answer is right, and anyone who wants the why is one link from the full April argument. Six minutes, once — versus a wrong answer propagating through support macros.

That banner-line move is worth stealing on its own: any doc that produced a promoted truth gets a one-line pointer to where the truth now lives. It is the cheap insurance against the superseded-snapshot problem, and it means even people who land on the old doc get routed to the current answer.

Sizing it: what this looks like at different scales

Under ~10 people: you can survive on docs alone plus one pinned "start here" page acting as a micro-wiki — ten links to the few things that must stay true. Adopt the routing rule anyway; the habit is cheap now and expensive to retrofit.

10–50 people: the full hybrid. A real wiki (expect it to stay small — 50–200 pages is healthy at this size), a docs area organized by team and project, promotion wired into project-close and decision rituals, one wiki gardener per area.

50+ people: the model holds, replicated per department, plus two additions: entry-point pages per audience (new hire, on-call, managers) because global navigation stops scaling, and a Q&A layer for demand-driven questions that neither container predicts — see why your team needs an internal Stack Overflow. The mature stack is three layers: wiki (curated truth), docs (working record), Q&A (demand-driven answers), with promotion flowing from the bottom two into the first.

Common failure patterns and their fixes

Pattern	Symptom	Fix
The everything-wiki	Meeting notes and drafts polluting reference; trust collapsing	Re-declare the routing rule; bulk-move working content out; wiki shrinks and recovers
The docs hoard	"It's in a doc somewhere"; five snapshots per search	Stand up a minimal wiki from the 20 most-needed truths; start promotion at next project close
The mirrored pair	Same content maintained in both places, drifting apart	One-place rule: durable claim in wiki, reasoning in docs, linked — never duplicated
The migration mirage	"We'll fix knowledge by moving tools" — same mess, new tool	The rule and ritual are the fix; migrate only the promoted layer by hand, on demand
The format war	Engineers demand markdown everywhere; ops demands blocks everywhere	Stop forcing one editor; markdown wiki + block docs lets both sides win where it matters

The mirrored pair deserves one more sentence, because well-meaning teams create it deliberately ("let's keep a copy in both so people find it either way"). Duplication is not findability; it is future divergence. The findability move is a link, which cannot drift.

Choosing tools for the hybrid

The requirements fall out of the model: a curated wiki surface (ideally markdown, with history and preview), a flexible docs surface (blocks, nesting), and — non-negotiably — one search across both, because readers do not know which container holds their answer, and the routing rule only pays off if both destinations are equally findable. Separate wiki and docs tools technically work but tax every search, every link, and every promotion with an app boundary; the promotion ritual in particular tends to die when it requires switching products.

Two secondary requirements earn a place on the checklist. Visible edit history on the wiki side — communal editing only feels safe when any change can be seen and reverted, and the fix-on-read habit dies without that safety net. Per-area visibility controls — the working docs of a compensation review need a smaller audience than the vacation policy, and if the tool cannot scope access per room or section, teams route sensitive work back out to email, which punches a hole in the one-search promise. Check both before committing; they are the requirements teams discover only after migration.

This is the shape Openbook builds in directly: a space can hold a Wiki room (markdown with side-by-side GitHub-flavored preview — the diffable, uniform, curated layer) and a Docs room (Notion-style block editor with infinitely nested pages — the expressive working layer) side by side, with global ⌘K search across both, so promotion is a copy-distill-link inside one workspace. Whatever tool you pick, hold the line on those three requirements; teams compromise on single-search first and regret it first.

Next steps

• Write the routing rule — steal the one-sentence version above — and post it where writing starts.
• Stand up the minimal wiki this week: the twenty pages your team most needs to be true, titled as questions where possible.
• Add the promotion line to your project-close and decision checklists, and name a wiki gardener per area.
• Schedule the first quarterly docs sweep now; 30 minutes, calendar it before enthusiasm fades.

If you want both containers under one search on day one, create a free Openbook space with a Wiki room and a Docs room — the features page shows both editors — and your "where should this go?" question gets a permanent, two-word answer: it depends on whether it needs to be true.