Inheriting a WordPress site often starts with a sinking feeling. You open the admin and see a theme you’ve never heard of, a plugin list long enough to need its own scroll bar, and a custom post type that clearly drives half the front page—yet nobody can tell you where it came from. Someone built this thing. That someone is gone. You’re now responsible for keeping it alive, and the only documentation you have is an email that says, “Let me know if you have questions.”
I’ve been building WordPress systems for over a decade, and I’ve had to untangle my own decisions months later. The documentation you leave isn’t a favor. It’s a professional obligation. If you care whether your work lasts—and whether the next maintainer, client, or future version of you respects what you built—you write it down.
This article is a field manual. I’ll walk through what to capture, how to structure it, and where to put it so the site outlives your direct involvement. No fluff. No generic advice. Just what I’ve seen work repeatedly on real WordPress projects.
Why Standard WordPress Documentation Fails
Most WordPress documentation that actually gets created lives inside a Google Doc, a pinned Slack message, or a sticky note on a monitor. These artifacts share a common flaw: they’re separated from the thing they describe. When the site changes—a plugin gets swapped, a custom function refactored, a content type renamed—the doc sits there, rotting, because nobody knows it exists or nobody has time to update it.
The second problem is scope. Documentation that tries to explain everything ends up explaining nothing. A 40-page PDF titled “Site Manual” is impressive until you need to find why the homepage query is slow at 2 a.m. You don’t need prose. You need a decision record, a map of dependencies, and a fast path to the source of truth.
A WordPress site is a living system. Your documentation must be as close to that system as possible, versioned alongside it, and ruthlessly focused on the parts that actually break or confuse people.
What the Next Maintainer Actually Needs
Before you write a single line, put yourself in the chair of the person who opens this site for the first time. They have a production issue, a client call in 20 minutes, and no context. They need three things immediately:
- A map of the critical paths: page templates, main queries, and custom functionality that touches the front end.
- A list of active dependencies: plugins, external services, cron jobs, and any API keys that aren’t stored in wp-config.php.
- The decisions you made and why: if you chose a particular caching strategy, a custom table, or a specific hosting configuration, explain the constraint that led you there.
Everything else—brand guidelines, content style guides, training videos—is secondary. Those are valuable, but they aren’t what prevents a site from going down. Document the architecture first, then the operations.
Where to Store Documentation So It Actually Survives
My rule: documentation that lives outside the project is documentation that will be lost. If you maintain sites for clients, you already know that handoff folders get buried in email threads, shared drives get reorganized, and Confluence spaces get archived when a contract ends. The only reliable container is the codebase itself.
I keep a /docs directory at the root of every WordPress project. Inside that directory, I use plain Markdown files with a naming convention that sorts logically: 01-architecture.md, 02-deployment.md, 03-plugins.md, and so on. This directory is committed to version control alongside the theme and custom plugins. When someone clones the repository, they get the documentation. When code changes, the commit message references the doc that needs updating. This isn’t a new idea—it’s standard practice in software engineering—but WordPress work often lags behind because so much of it starts as a visual build rather than an engineered system.
Inside the Admin: The Dashboard Note Pattern
For context that must survive even if the repository isn’t immediately available, I add a single admin dashboard widget using a small mu-plugin. This widget displays a concise summary: the PHP version requirement, the critical plugin list, the custom post types registered by the theme, and a link to the full documentation in the repo or a shared drive. It’s visible on login, impossible to miss, and takes ten lines of PHP.
This pattern is especially useful when the next maintainer is a site owner or a less technical person who won’t be cloning repositories. They see the essential facts before they click anything. If you’ve ever had a client update PHP without telling you and then call in a panic, you understand why this matters.
What to Document: The Minimum Viable Set
You can’t document everything. If you try, you’ll burn out and the result will be a 60-page monster that nobody reads. Instead, document the minimum viable set: the information that, if missing, would cause someone to break the site or waste hours reverse-engineering your choices.
1. Hosting, DNS, and Access
This sounds obvious, but I’ve inherited sites where the previous developer was the only person with the hosting login and the domain was registered to an email address that no longer existed. Document the hosting provider, the plan level, the primary contact method for support, and where the domain is registered. If you use a CDN or external DNS service, list it. Don’t put passwords in a plain text doc, but do note which password manager or shared vault holds them.
2. Theme and Child Theme Architecture
State whether the site uses a parent theme, a full custom theme, or a block theme. List the primary template files and what they control. If the theme has custom page templates, name them and describe their purpose in one sentence. Note any hardcoded template parts that load specific pages or sections—these are the first things that break when someone edits a page slug.
3. Plugin Inventory with Purpose
Don’t just export a plugin list. Annotate it. For every active plugin, write one line explaining why it’s there and whether it’s safe to deactivate. Mark plugins that are mu-plugins or that are loaded via Composer. If a plugin has a custom configuration stored in the database rather than in code, note where to find that setting. This is also where you flag plugins that are unmaintained, forked, or held at a specific version because of a compatibility issue.
4. Custom Functionality and Hooks
If you have a custom plugin or a functions.php that does more than enqueue styles, document the hooks and filters. List any REST API endpoints you’ve added or modified. Describe custom WP-CLI commands. For each piece, explain the business logic in plain language: “The pre_get_posts filter on the blog archive excludes posts in the ‘internal’ category so they don’t appear on the public site.” The next person shouldn’t have to read the PHP to understand the intent.
5. Content Structure
Detail the custom post types and taxonomies registered outside of core. For each, note the slug, the archive page, and any relationship to other content types. If a custom post type is created by a plugin, name the plugin. If you have ACF field groups or block-based patterns that define the editing experience, document those as well—especially if certain fields are required for a template to render correctly. A site that suddenly shows “Nothing Found” on a key page often has a content structure problem that traces back to a missing field or a changed slug. I’ve written about diagnosing that exact scenario in What to Fix First When a New WordPress Site Says Nothing Found.
6. Build and Deployment Process
If you use a build tool (Webpack, Vite, Gulp), document the commands to install dependencies, compile assets, and deploy. Note the Node version and any environment variables required. If deployment happens via Git push, CI/CD pipeline, or a manual SFTP sync, describe the exact steps. This section saves hours of guessing when someone needs to push a hotfix at an odd hour.
7. Scheduled Tasks and External Integrations
List every cron job—both WordPress cron events and server-level crontabs. Note any webhooks that send or receive data, including the service they connect to and the expected payload. If an integration depends on an API key stored in wp-config.php, name the constant. The next maintainer should be able to look at this list and immediately know which external systems will fail silently if a key expires or an endpoint changes.
Writing Style That Doesn’t Waste Time
Technical documentation isn’t a place for personality or marketing language. Write short, declarative sentences. Use the imperative mood for instructions: “Set the PHP version to 8.1.” Not “The PHP version should be set to 8.1.” Use consistent terminology—if you call something a “block” in one place, don’t call it a “module” in another.
Every section should answer three questions: What is this thing? Why does it exist? What happens if I change it? If a sentence doesn’t serve one of those answers, cut it.
Include dates. A doc that says “Last updated: March 2025” is immediately more trustworthy than one with no timestamp. The reader knows whether they’re looking at current information or a historical artifact.
Maintenance: Keeping Docs Alive
Documentation decays. The only defense is to make updating it part of the development workflow. When I close a task or merge a pull request, I check whether the change affects something in the docs directory. If it does, I update the docs in the same commit or a linked commit. This isn’t extra work—it’s part of the definition of done.
For larger sites with multiple contributors, I add a section to the pull request template: “Does this change require a documentation update? If yes, which file?” This simple prompt catches most omissions before they become problems.
What to Do When You Inherit an Undocumented Site
You’ll eventually be on the other side of this equation. When you inherit a site with no documentation, start by creating the docs you wish you’d received. Open a docs/README.md and begin filling in the sections listed above as you discover them. Do this during your first week, while the pain of not knowing is fresh. You’ll save your future self dozens of hours, and you’ll hand off a better asset when your time on the project ends.
If you’re stepping into a site that already has issues—broken permalinks, missing pages, a front page that refuses to display content—start with the structural diagnosis I outlined in What to Fix First When a New WordPress Site Says Nothing Found. Fix the visible breaks, then immediately document what you fixed and why. That doc becomes the first page of the new site manual.
FAQ
How long should site documentation be?
As long as necessary and no longer. A small brochure site might need only a single README with 300 words covering hosting, theme, and plugins. A complex membership site with custom APIs and a multi-server deployment might need several files totaling a few thousand words. The test: if you can hand the doc to a competent WordPress developer and they can fix a critical bug within an hour, it’s long enough.
Should documentation include screenshots?
Screenshots are useful for admin settings pages that are hard to describe in text—for example, a complex plugin configuration screen with many toggles. But they rot quickly because interfaces change. Use them sparingly and always accompany them with a text description of the setting and its expected value. The text is the source of truth; the screenshot is just a visual confirmation.
What if the client refuses to pay for documentation?
Build the cost into your development estimate from the start. Treat documentation as a deliverable, just like the theme files or the deployment script. If a client explicitly cuts it from the scope, you have a choice: do it anyway as a professional courtesy (it protects you from support calls later), or walk away knowing the project will become a maintenance liability. Most clients don’t object when you frame documentation as the thing that lets anyone else—including their internal team—support the site without calling you for every small change.
How do I document a site that is still changing frequently?
Document the stable parts first: hosting, deployment, plugin inventory, content structure. For areas under active development, add a note that says “This section is in flux as of [date]” and link to the relevant project board or issue tracker. Update the doc when the feature stabilizes. Imperfect documentation that reflects the current state is better than perfect documentation that never gets written.
The mark of a serious WordPress engineer isn’t the complexity of the code they write. It’s whether the next person can pick up their work and keep the site running without wanting to find them and ask pointed questions. Write the docs you wish you’d received. Your reputation—and your sleep—will thank you.