The engineering handover checklist

Most handovers happen in a rush. Someone is leaving on Friday, a project is being reassigned, or a vacation is finally booked — and suddenly a service that has run quietly for two years needs to make sense to someone else. So you block an afternoon, talk fast, and hope the important parts stuck. A week later the questions start arriving anyway.

There is a calmer way, and it does not require more time — it requires a checklist. A handover is not a heroic download of everything in your head. It is a short, repeatable list of what a capable teammate needs to run a system without you. Work through it once and you leave behind a runbook, not a mystery. Let us build that checklist together.

Start with the system only you understand

You do not have to document everything at once. Pick the one service you would least like to explain over the phone on a day off — the one with the quirks, the manual step, the reason nobody else has touched it. That is your bus factor of one, and it is where a handover pays off first.

Everything below fits on a single page per system. If it grows past two pages, you are probably writing a history book instead of a runbook. Keep it to what someone needs to act.

The six sections of a runbook that works

A runbook is just well-organized answers to the questions a newcomer will actually ask, in the order they will ask them. Six sections cover almost every system:

1. Overview — what this service does, who owns it, and where it lives (repo, cloud project, region). Two or three sentences. If a new hire read only this, they should know what they are looking at.
2. Access & on-call — how to reach the thing: dashboards, log locations, the on-call rotation, and how alerts are wired. Name where access is granted, not the credentials themselves.
3. Deploy — the exact, safe way to ship a change. Commands or pipeline steps, written so a calm newcomer could follow them at 4pm on a Tuesday.
4. Rollback — how to undo a bad change, and how to tell it worked. This is the section people reach for when a shift gets tense, so make it the clearest one you write.
5. What breaks and why — the honest section. The known sharp edges, the log line that means trouble, the workaround everyone forgot to write down, and the one config that must never be touched without care.
6. Links & where the secrets live — pointers out: the dashboards, the design doc, the ticket queue, and the name of the entry in your secrets store (never the secret itself).

Fill those six in for one service and you have a real handover. Tomorrow, do the next system. For the section-by-section wording, the runbook writing guide goes deeper on each one.

Map access, don't hoard it

The quiet thing that makes one person irreplaceable is access. If you are the only one who can reach the logs, approve the deploy, or read the alert, no amount of documentation hands the system over.

So map it plainly. In the Access section, list every place a teammate needs standing to help: the dashboard, the deploy pipeline, the cloud role, the paging tool. Note who grants each one. Then — before the handover, not during it — make sure at least one other person actually has that access. A runbook a teammate cannot act on is a story, not a handover.

Keep secrets out — a runbook, not a secrets vault

Here is the one hard line in the whole system, and it never bends.

It is tempting, while writing, to paste a real token "just so the example works." Do not let that paste become permanent. A runbook is something you will copy into a wiki, sync across devices, and hand to a new teammate — all the things you must never do with a secret. Keep the two apart from day one and your runbook stays safe to do anything with.

Raise your bus factor on purpose

"Bus factor" is the gentle old name for a simple question: how many people would need to be unavailable at once before a system becomes hard to run? Think of it as the lottery factor — if a teammate won the lottery and happily walked off tomorrow, how many systems would be stranded?

A handover checklist raises that number on purpose. Once a runbook exists, do one more thing: have someone else use it. Ask a teammate to run a routine deploy or a practice rollback from your runbook while you watch quietly and only answer if they get stuck. Every place they stumble is a line your runbook was missing. Twenty minutes of this is worth more than an hour of you talking. The bus-factor guide covers how to spread that knowledge across a whole team without heavy process.

Keep it current: the five-minute habit

A runbook that is out of date is worse than none, because people trust it. The upkeep is tiny, though. Once a change teaches you something — a new alert, a renamed pipeline, a step that turned out to matter — add the line right then, while it is fresh. That is the whole maintenance cost.

Once a month, spend five minutes skimming the runbooks for the systems you own. Fix anything that has drifted, delete anything no longer true, and note anything a recent incident revealed. A living runbook is the difference between "we have docs" and "we can hand this over."

Where to keep your runbooks

The checklist is deliberately tool-agnostic, because the method is what matters. Runbooks live happily in plain Markdown in the repo (closest to the code), in a team wiki (easy to browse), or in Notion (nice for links and search). Put them where your team already looks. If you want the structure ready-made, the free Handover Quick-Start gives you the checklist and the six-section skeleton to paste into any of them today — and the Starter turns it into a full template set for your first real system.

The handover checklist: FAQ

How long should a handover take?

Less than you think, if you use a checklist instead of trying to transfer everything by memory. Budget twenty focused minutes per system to fill in the six sections, then a short session where a teammate runs the runbook while you watch. A whole service can be genuinely handed over in an afternoon.

What is the single most important section?

Rollback, closely followed by "what breaks and why." When a shift gets tense, people do not need history — they need the clear, calm steps to make things safe again. Write those two sections for a tired newcomer and the rest gets easier.

How is a runbook different from our wiki?

A wiki is a place; a runbook is a shape. Most wikis are a pile of pages nobody trusts because there is no standard for what a page should contain. A runbook is the standard: the same six sections, every time, so a teammate always knows where to look. See runbook vs. wiki for what goes where.

What if I am the one leaving soon?

Start today with your riskiest system and work down the list. Prioritize access and rollback over completeness — a teammate who can reach the system and undo a bad change is already most of the way there. The pre-departure list is a calm place to begin.

Do I need special software for this?

No. A handover is knowledge organized well, and any editor, wiki, or plain folder will hold it. The habit is the product; the tool is just where it lives. Keep credentials in a real secrets store, and keep the how-it-works in your runbook.

Keep reading

• How to Write a Runbook People Actually Read
• How to Reduce Your Team's Bus Factor (Without Heavy Process)
• What to document before you leave