The test
A WordPress build is documented well enough when a competent developer who has never seen it can set it up locally, understand how the content model works, deploy a change to production and know what would break if they removed a plugin, without emailing you. That is the whole standard. Everything below is in service of it.
Most builds fail the test not because nobody wrote anything, but because what was written answers the wrong questions.
What to include
One document, in the repository, as README.md or a docs/ folder. Seven sections.
1. What this site is
Two paragraphs. Who the client is, what the site does, what matters most (the booking flow, the store, the member area). The next developer should know within a minute where the risk lives.
2. Local setup
The exact steps to run it locally. Which tool, which PHP version, how to get a database copy, how to get the environment file, how uploads are proxied from production. Tested by someone other than the author, because the author's machine already has everything installed.
3. Architecture
- Theme: name, block or classic, where the design tokens live.
- Site plugin or mu-plugin: what it registers and why it is separate from the theme.
- Content model: each custom post type and taxonomy, what it represents, its key fields, and which templates render it. A table is enough.
- Third-party plugins: each one, what it does for this site, and whether anything custom depends on it. This is the list that answers "can I remove this".
- Integrations: booking system, email service, payment gateway, analytics. Where credentials live and who owns the accounts.
4. Deployment
How code gets to staging and production. Which branch deploys where. How to roll back. How the database and uploads are handled between environments. What the caches are and how to clear them.
5. Editing
How the client edits: which things are fields, which are blocks, which patterns are locked. A link to the recorded walkthrough given to the client. This section prevents the next developer "fixing" a constraint that was deliberate.
6. Known issues and decisions
The things you would tell a colleague over coffee. "The gallery plugin is held at 3.2 because 3.3 breaks the theme's lightbox." "Services are ordered by a menu_order field the client sets manually, on purpose." "The old URLs from the 2022 site redirect via the server config, not a plugin." Decisions without their reasons get reversed.
7. Accounts and access
Not the passwords. Where they are (a password manager, the client's), who owns each account, and who to ask. Domain registrar, hosting, booking tool, email service, analytics, any API keys.
What to leave out
- Generic WordPress documentation. Link to it if needed; do not restate it.
- Code comments copied into prose. The code has comments; the document explains what the code does not.
- Screenshots of every admin screen. They are out of date by the second release.
- Marketing about the project.
Where it lives
In the repository, versioned with the code, so it changes when the code changes. A copy of the client-facing parts, editing and accounts, goes to the client. Nothing lives only in an email thread or a chat channel.
Keeping it current
The document is updated in the same commit as any change that would make it wrong. A new plugin: added to the plugin list. A held-back update: added to known issues. A new integration: added to accounts. Documentation that is updated "later" is documentation that is wrong.
A quick review at each monthly maintenance pass catches drift.
Why it is part of the scope
Documentation is often the first thing cut when a project runs long, because the client cannot see it. That is exactly backward: the client is the one who pays when it is missing, in the day rate of the next developer reverse-engineering the build, or in the lock-in of only being able to call you.
It is part of every WordPress project we deliver, and the acceptance test is the one at the top: could another developer pick this up? If the honest answer is no, the project is not finished.