WordPress Handoff Standards: Documentation Clients Actually Use

Six weeks after a site launches, the client emails asking how to add a team member to the about page. Nobody on your side remembers which custom field controls that block. The developer who built it has moved to another project. What you send back is a fifteen-minute Loom recorded in a hurry, and it will be lost by the time the next question arrives.

Good WordPress project handoff documentation is not a nice-to-have at the end of a build. It is the thing that decides whether a launched site becomes a retainer or a slow drip of unbilled support. This post covers what to document, what to deliberately leave out, the format clients actually open, and how to produce it without adding days to every project.

Why most handoff documents go unread

Agencies usually fail in one of two directions. Either the handoff is a 40-page PDF that documents WordPress itself, or it is a folder of credentials and a link to a video. Both get ignored, for the same underlying reason: they are organised around the build rather than around what the client will actually try to do.

Nobody reads documentation for pleasure. People read it at the exact moment they are stuck, with a specific task in mind, usually under time pressure. Structure it as a set of answers to tasks and it gets used. Structure it as a narrative of how the site was built and it does not.

• Explaining what a plugin is, instead of explaining which plugin controls their popup
• Screenshots of an admin screen that will look different after the next core update
• Technical architecture notes mixed into content-editing instructions
• No search, because it is a PDF attached to an email from March

Split it into three documents, not one

The single biggest improvement you can make is separating audiences. Three short documents beat one long one, because each has a clear owner.

Document	Audience	Contains	Length
Editor guide	The client’s marketing or content person	Task-based instructions for editing the site	4-8 pages
Technical handover	Whoever maintains the site next	Stack, custom code, cron, integrations, gotchas	3-6 pages
Access and asset register	The client’s operations or admin owner	Where everything lives and who owns each account	1-2 pages

The register is the one agencies most often skip and the one clients most often come back for. Two years later, when a domain is due for renewal or an SSL certificate lapses, that page is worth more than everything else combined.

What belongs in the editor guide

Write it as tasks. Each entry is a heading phrased the way the client would ask the question, then the shortest accurate answer, then a note about anything that will break if they get it wrong.

1. How to log in and who has access. Include the role each person has and what that role can and cannot do.
2. How to edit each page type. One entry per template. Say which parts are editable and which are locked, and why.
3. How to add a post, product, case study or team member. Cover the required fields and image dimensions explicitly.
4. How to change navigation, footer and global elements. These are usually the first things a client breaks.
5. How images should be prepared. Dimensions, formats, and a plain warning about uploading 6MB photos from a phone.
6. What not to touch. A short, direct list: theme files, plugin settings, permalinks, the hero block markup.
7. Who to contact and how. Your support channel, hours, and what counts as urgent.

Use short screen recordings for the three or four tasks that are genuinely fiddly, and link them from the relevant section. Video works as a supplement and fails as the primary format, because nobody can skim it.

The technical handover

This one is written for a developer you have never met, possibly at another agency, possibly in three years. Assume they are competent and impatient. Cover the things they cannot infer from reading the code.

• Environment map. Production, staging and local. Hosting provider, PHP version, database details location, and how deployments happen.
• Repository and branching. Where the code lives, what the branch strategy is, and what is intentionally not in version control.
• Custom code inventory. Every custom plugin, theme override, must-use plugin and snippet, with one line on what it does.
• Third-party integrations. CRM, payment, shipping, marketing automation. Note where API keys are stored and who owns each account.
• Scheduled jobs. Real cron or WP-Cron, what runs, when, and what fails silently if it stops.
• Known trade-offs. The compromises you made and why. This is the most valuable section and the one most often omitted.

Deployment specifics deserve their own short section, because that is where an unfamiliar developer will do the most damage fastest. Point them at your process rather than describing it loosely; our write-up of a safe staging to production deployment workflow works well as a linked standard. If the site has locked-down roles, document those decisions too, in the way we describe in locking down editor roles and permissions.

Handoff standards for white label work

When a development partner builds under your brand, documentation is part of the deliverable and it has to arrive unbranded, editable, and in your house style. Set that expectation in the scope, not after the build.

• Documents supplied in an editable format, so you can rebrand and adapt them
• Zero partner branding anywhere, including file metadata, commit authors and email footers
• Full code ownership transferred on delivery, with no licensing strings on custom code
• An NDA covering the client’s material, in place before the build starts
• All communication routed through your project management tool, never direct to your client

Those are the terms we work to on every plan, and they are the baseline you should hold any partner to. The broader argument for structuring outsourced delivery this way is in our guide to white label WordPress development for agencies, and the documentation standard itself is part of what we deliver under white label WordPress development.

Producing documentation without burning days

The reason handoff docs are thin is that they get written at the end, when the budget is gone and the team has moved on. Fix the timing, not the effort.

1. Keep a template repository with the three documents already structured. You are filling gaps, not starting from a blank page.
2. Write the technical handover as you build. Every time you make a non-obvious decision, add two lines. It costs a minute and saves an hour.
3. Draft the editor guide during QA, when you are already clicking through every template as a user would.
4. Budget documentation as a named line item in the estimate, typically 3-5% of build hours. If it is not in the quote, it will not get done.
5. Do a live 45-minute walkthrough at handover and record it. Then link the recording from the guide, timestamped.
6. Review and update it at the first quarterly maintenance check, so it does not rot.

Documentation that is reviewed on a schedule stays true. Documentation that is written once and filed becomes actively misleading within about a year, which is worse than having none. Sites under an ongoing WordPress maintenance and support arrangement should have the register checked at every review cycle, alongside backups and updates. If you are packaging that as a client offer, our post on maintenance retainers for agencies covers how to price the ongoing work.

A one-page handoff checklist

• Three documents delivered: editor guide, technical handover, access register
• All accounts transferred to client-owned emails, not personal ones
• Admin users audited; developer accounts removed or downgraded
• Backups configured, tested by restoring once, and documented
• Staging environment either handed over or explicitly decommissioned
• Analytics, Search Console and tag container ownership confirmed
• Support terms in writing: what is covered, what is billable, response times
• Recorded walkthrough delivered and linked from the editor guide

Frequently asked questions

Should handoff documentation be a PDF or a living page?

A living page, hosted somewhere the client can search it, with a PDF export for their records. PDFs go out of date and get buried in inboxes. A shared doc or a private page on the site itself is far more likely to be used.

How much should we charge for documentation?

Include it in the build price as a named deliverable rather than an optional extra. Clients rarely approve documentation as a line item they can decline, and you will end up producing it anyway when the support requests start.

What if the client never reads it?

Some will not, and that is fine. The document still pays for itself twice: it shortens your own support answers to a link, and it protects you when a third party takes the site over and asks how it was built.

Do we hand over the staging site as well?

Decide explicitly and write it down. Either the client keeps staging as part of a maintenance arrangement, or you decommission it at handover. An abandoned staging copy is a security and duplicate-content liability nobody is watching.

Can a white label partner write documentation in our brand voice?

Yes, if you supply a template and a tone reference at kickoff. Give the partner your existing editor guide from a previous project as the model. Without that, you will get a competent document that reads like someone else wrote it, because someone else did.

If handoff quality is slipping because builds keep running to the wire, a dedicated monthly block of development capacity gives you the slack to do it properly. You can see how our dedicated plans are structured, or start a conversation about a single project first.