Picture the person who will one day open your system's runbook. They have never seen the code. The person who built it is unreachable, on a flight or simply long gone. Something has stopped working, a customer is waiting, and all they have is a document. Whether that afternoon is a disaster or a nuisance depends on what the document says.
A runbook is not a design document. It is a short, plain-English set of instructions for running the thing, written for someone competent who is new to it: a developer you hire later, a colleague who is good with computers, or you. Here is what goes in one.
What it is
Open with what the system does for the business, in the words the owner would use. Not "a PHP application with a scheduled worker", but "the booking form on the website, and the job that sends confirmation emails every five minutes". Then the technical summary: language, framework, database.
A reader should know within a minute whether they are holding the right document.
Where it runs
Every place the system lives: the hosting account, the domain and its registrar, where DNS is managed, the database, and every outside service it depends on (payments, email, file storage). For each, note which account it sits under and who owns that account.
The usual gap in a handover is not missing code. It is a domain renewing against an expired card, or a hosting account tied to the personal email of someone who left. Nobody notices until the renewal fails.
How to deploy it
The exact steps to put a change live, as commands someone can copy, in order: where the code is kept, which branch is live, how to build and publish it, how to check it worked, and how to roll back. Rolling back is the step people leave out, and the one you need most under pressure.
If deploying depends on something that exists only on one laptop, that is a fault to fix before handover, not a detail to document.
Credentials, and who holds them
The runbook lists credentials. It never contains them.
Passwords pasted into a document get copied, forwarded and forgotten. Write down what each credential is for, where it is stored (a password manager the business owns, the hosting control panel) and who holds it, then name a second person for each. A login only one person can use is an outage waiting for that person's holiday.
By the end of a handover the business should own every account, and be able to change every password without asking the person who built it.
What breaks, and how you can tell
Every system has a short list of things that go wrong: a disk fills up, a certificate expires, a scheduled job stops without telling anyone. Write each down in three lines: the symptom someone will see, where to confirm it, and the fix.
Lead with the symptom, because the stranger does not know the cause yet, only what the customer said: "confirmation emails have stopped". Add a note on what healthy looks like, too. It is hard to spot what is wrong if nobody told you what normal is.
Who to call
Names, roles and how to reach them, plus each provider's support route. Include one name that is easy to forget: who can approve spending money in a hurry, because "should we pay for a bigger server tonight?" tends to come up at awkward hours.
The person who built the system belongs on this list, but as one option among several. If the whole plan is "call the developer", there is no plan.
The skeleton
Put together, the outline is short:
RUNBOOK: Booking system
Last followed end to end by: <name>, on <date>
1. WHAT IT IS
One paragraph for the owner. One for the engineer.
2. WHERE IT RUNS
Hosting: <provider>, account owner <name>
Domain: <registrar>, renews <month>
Database: <engine, location>
Other: <email, payments, storage>
3. HOW TO DEPLOY
Code: <repository>, live branch <name>
Deploy: <exact commands, in order>
Check: <how to confirm it worked>
Roll back: <exact commands>
4. CREDENTIALS (where they are, never what they are)
<credential> stored in <place> held by <person>, second <person>
5. WHAT BREAKS AND HOW TO TELL
Symptom: <what a user sees>
Confirm: <log or check>
Fix: <steps>
6. WHO TO CALL
<name, role, phone, email>
<provider support routes>
Can approve spending: <name>Note the line at the top. A runbook goes stale quietly, so it records who last followed it end to end, and when. The real test is to hand it to someone new and watch. Where they get stuck, the runbook is wrong, not the reader.
Why every job gets one
I have been selling software since 2001, and I work as one engineer: no agency, no account managers, no junior to hand the work down to. Anyone hiring a one-person practice is entitled to ask the obvious question. What happens if you are unavailable? "Nothing will go wrong" is not an answer. A document is.
So every handover comes with the code, the credentials and a runbook in plain English. It is also the most honest review my own work gets: if a system cannot be explained to a stranger in a few pages, it is more complicated than it needed to be. Things should keep working long after my involvement ends. The runbook is how that sentence stays true.
