Handover craft · 4 min read
Runbook vs. wiki vs. README
The reason team documentation turns into a swamp is rarely laziness — it is that nobody agreed on what goes where. Here is a calm, simple split between README, runbook, and wiki, so every fact has one obvious home.
Documentation rarely fails because people are lazy. It fails because nobody agreed on what goes where. So the same fact gets written in three places, each slightly out of date, and soon nobody trusts any of them. The wiki becomes a swamp, the README is stale, and the real answers migrate back into people's heads — which is where you started.
The fix is boring and effective: give each kind of knowledge one obvious home. There are really only three homes you need, and each has a distinct job. Once your team shares this split, the swamp drains on its own, because every fact has exactly one place to live.
Three homes, three jobs
Think of it as three different questions a person might be asking:
- README answers "how do I work on this code?"
- Runbook answers "what do I do to operate it, especially right now?"
- Wiki answers "how does this work, and why is it this way?"
Keep those questions separate and you will almost always know where a piece of information belongs.
README: for the person editing the code
The README lives in the repo, next to the code, because its reader is a developer working on that code. It covers how to set up the project locally, how to run the tests, the layout of the codebase, and how to contribute. It changes when the code changes, which is exactly why it belongs in the repo — the same pull request updates both.
Keep the README about developing the thing. The moment you start writing "if the service is misbehaving in production, do X," you have wandered into runbook territory.
Runbook: for the person operating it
The runbook is the action document. Its reader is on-call or covering a shift, and it answers "what do I do" — deploy, roll back, respond to this alert, recover from this common problem. It is short, ordered, and written for the tired newcomer, which is the whole point of the 2am test.
Because it is the document people reach for under stress, the runbook is the one that has to be right. It is worth writing carefully and testing by having someone follow it. The runbook writing guide covers the shape; the short version is: exact steps, rollback near the top, and a clear "how do I know it worked?"
A quick test for whether something is a runbook or a wiki: would someone read it while acting, or while learning? Acting means runbook — keep it lean and literal. Learning means wiki — give it room for context.
Wiki: for the person trying to understand
The wiki is the home for context and reasoning — architecture overviews, design decisions, "why we chose this database," team processes, and the history that helps someone understand the system deeply. Its reader has time and curiosity, not an alert. It is fine for wiki pages to be longer and more discursive; that is their job.
The wiki is also where a runbook links out for background. A runbook says "restart the worker (see the architecture page for why it deadlocks under load)." The action stays in the runbook; the explanation stays in the wiki. Each does one job well.
Drain the swamp: link, don't duplicate
The single habit that keeps documentation clean is one home per fact, and link to it. If the deploy steps live in the runbook, the wiki does not repeat them — it links. If the architecture reasoning lives in the wiki, the runbook does not re-explain it — it links. Duplication is what rots, because two copies drift apart and readers stop trusting both.
One line runs through all three homes: none of them is a place for secrets. Wherever a step needs a credential, name where it lives in your secrets store and link to it. A README, a runbook, and a wiki are all things people copy and share, which is exactly why they must stay runbooks, not secrets vaults.
Agree on this split with your team, and documentation stops being a source of guilt. Every question has a home, every fact has one place, and the engineering handover checklist ties the operational half together. If you want a clean runbook to start with, the free Handover Quick-Start gives you the skeleton — the one part of your docs that most repays getting right.
The runbook skeleton — the one part of your docs that has to be right.
Runbook vs. Wiki vs. README: What Goes Where: FAQ
What if something feels like it belongs in two places?
Put it in the home that matches how it will be read, then link from the other. Deploy steps read under stress belong in the runbook; the reasoning behind them belongs in the wiki. One home plus a link beats two copies that slowly disagree.
Do small teams really need all three?
You need the split more than the tooling. A tiny team might keep the README in the repo and both runbooks and wiki-style notes in one wiki — that is fine, as long as runbook-style action docs stay lean and separate from long-form context. The point is clarity about what each page is for.
How do we stop docs from going stale?
Keep each fact in one place, update it the moment reality changes, and link rather than duplicate. Runbooks especially earn a quick monthly skim. Stale docs usually come from duplication, so removing copies is the highest-leverage fix you can make.
Keep reading
- How to Write a Runbook People Actually Read
- The Engineering Handover Checklist (A Calm, Complete System)
Disclaimer: The Handover Folder is a documentation tool, not a secrets manager. Never paste credentials, tokens, or private keys into a runbook — reference them from your real secrets store.