It is a Friday evening and a client’s booking form has stopped sending. The developer who built the site is on leave. Someone else opens the dashboard and starts asking the questions that should already have answers. Which form plugin? Where do the emails go? Is there an SMTP service, and who has the login? Is there a staging copy? What was changed this week? Every one of those answers exists somewhere, in a chat thread, an old proposal or one person’s memory, and finding them takes longer than the fix.
Agencies that run smoothly tend to have one unglamorous habit in common: every client site has a short written record that anyone on the team can open and act on. Call it a runbook, site notes or a site file. This post explains what to put in one, where to keep it, how to stop it going stale and how to get it done for sites you already look after.
What a runbook is, and what it is not
A runbook is a practical reference for working on one site. It answers “how do I do the common things here, and what do I need to know before I touch it?” It is not a design document, a proposal or a full technical specification. If it takes more than a few minutes to read, it will not be read when it matters.
Think of three readers: a developer who has never seen the site, your account manager talking to the client, and you in a year’s time when nobody remembers why that odd plugin is installed. If all three can use it, it is doing its job.
A template you can copy
Keep the same headings for every site so people know where to look. Leave a section blank, or write “none”, rather than deleting it; an empty section is information too.
1. Summary
- Client name and site address
- What the site does for the business, in one line (“takes appointment bookings”, “sells spare parts”)
- The pages and features that must never break
- Busy periods and any dates when changes should be avoided
- Who at the agency is responsible for this client
2. Accounts and access
- Registrar, DNS provider, host and email provider, with whose name each account is in
- Where the logins are stored (the password manager entry, never the password itself)
- Which outside services connect to the site: payments, CRM, newsletter, analytics, chat
- Renewal dates for domain, hosting and premium licences
3. Technical setup
- Theme and child theme, and whether there is custom code and where it lives
- Plugins that are not part of your usual set, with a line on why each is there
- Caching layers: plugin, host, CDN, and how to clear each
- How email is sent from the site
- Scheduled tasks that matter, such as imports or reminder emails
- PHP version and anything known to depend on it
4. Backups and environments
- How backups are taken, how often, where they are stored and how long they are kept
- The last time a restore was tested
- Whether a staging copy exists, how to reach it and how changes get from staging to live
5. Known quirks
This is often the most valuable section. “The menu caches separately; clear it after edits.” “The client’s office network blocks the admin login page; they use a VPN.” “The product import fails if the spreadsheet has blank rows.” Each quirk you write down saves someone an hour.
6. Common tasks
Short step lists for the jobs that come up repeatedly on this site: adding a team member to the about page, updating opening hours, adding a product, changing a form recipient.
7. If something breaks
- Who to tell at the agency, and who at the client (with how they prefer to be contacted)
- What to check first for this site in particular
- Whether the database may be restored without asking (on a store or booking site, usually not)
- Host support route and any account number they will ask for
For the bigger picture of handling a security incident, link this section to a shared plan. Our post on a one-page security incident plan offers a template that sits alongside the runbook.
8. Change log
A dated, one-line entry for every meaningful change: what, who, and why. “Replaced slider plugin with core blocks, at client’s request.” This is the section people skip, and the one they most often wish existed.
Where to keep it
The right tool is whichever your team already opens every day. A shared drive folder, a wiki, a project management tool or a notes app shared across the team all work. What matters more than the tool:
- One place per site. Not a doc in one system and the logins in another without a link between them.
- Everyone who works on sites can read it, including outside partners, with access removed when they stop working with you.
- No secrets in the document. Point to the password manager entry instead. Documents get shared, exported and forwarded; passwords in them end up in places you never intended.
- Easy to find from a ticket. If your ticket system or project board allows it, link the runbook from the client’s record so it is one click away.
Some agencies also keep a short README in the site’s code repository for the technical parts. That is useful, but the account manager and the client-facing details still need to live somewhere non-developers can reach.
Keeping it current
Documentation decays from the day it is written. The fix is to make updating it part of the work rather than a separate task.
- Close every job by updating the runbook. If a ticket changed anything worth knowing, the ticket is not done until the note is updated. Make it a line in your definition of done.
- Write the quirk when you find it. Not at the end of the week. The detail is gone by then.
- Review on a schedule. Once or twice a year, open each runbook and check the basics against the live site: plugin list, PHP version, backup setup, contacts.
- Use it during handovers. When work passes from one person to another, walk through the runbook together. Gaps show up quickly when someone reads it cold.
Getting it done for sites you already run
The hardest runbook to write is the one for the site you have looked after for years without one. Trying to document the whole portfolio in one push rarely works. A gentler approach:
- Start with the sites that would hurt most to lose. Stores, booking sites and your largest clients first.
- Fill in sections 1, 2 and 7 first. Summary, access and “if something breaks” are what you need in an emergency. The rest can follow.
- Write the next section whenever you touch the site. Every ticket on an undocumented site adds a bit more.
- Use the onboarding audit as a starting point. If you audited the site when you took it on, much of the technical setup is already written somewhere. The sibling post on checking an inherited client site before you commit describes an audit whose findings drop straight into a runbook.
Runbooks and handovers
A good runbook makes every kind of handover easier. When you finish a build and hand the site to a client or to another team, the runbook is most of the handover pack; the post on handing over a finished site covers what else goes with it. When a client leaves, a clean copy of the non-confidential parts is a professional thing to give them.
It also changes how you brief outside help. Instead of writing the site’s background into every request, you link the runbook and describe only the job itself. That keeps briefs short and specific, which is the whole argument of our guide to briefing outside developers so they can start without questions.
Useful notes versus useless ones
The difference between a runbook people trust and one they ignore is usually the wording of individual entries. Compare:
- “Email is set up.” versus “Site email goes through the client’s email provider via an SMTP plugin. Credentials are in the password manager under the client’s name. If form emails stop, check the plugin’s email log first.”
- “Be careful with updates.” versus “The events plugin overrides the theme’s single-event template. After updating either, check one event page on staging.”
- “Client is fussy.” versus “Client wants to approve any visible change on the homepage before it goes live, by email to the office manager.”
The second version in each pair tells the reader what to do. That is the test for every line.
Small habits that make the difference
- Date every entry. Undated notes cannot be trusted.
- Write for someone who has never seen the site, without assuming they know your shorthand.
- Prefer short steps to paragraphs.
- Note who told you something, especially when it came from the client (“client confirmed they do not use the old newsletter list”).
- When a note turns out to be wrong, correct it straight away and say what changed.
None of this is complicated, and none of it needs special software. It needs a template, a home for it and the discipline to update it at the end of each job. It is also the foundation that makes sharing work with a partner manageable; our guide to how agencies outsource WordPress work shows where runbooks fit in that arrangement.
If you would like a team that keeps these notes as part of looking after your clients’ sites, the page on white label WordPress maintenance explains how we work and what we send back after each job.
Next in this series: Client Data Privacy When Agencies Outsource WordPress Work
