I Built a Documentation Site for an AI Agent, Not Just a Developer

In the last article we made FictionalWPSEO easier to understand: concrete facts instead of “powerful and flexible.” It supports custom post types, has a PHP API, provides hooks, works with WooCommerce, exposes selected functionality through REST, and clearly says what it doesn’t support.

Good start. New problem: where does all this information actually live? Some on the homepage, some buried in FAQs, some in blog posts, some in developer docs, and maybe one important example only exists in a support ticket from six months ago. A developer can burn twenty minutes finding the answer. An agent faces the same problem.

Documentation is becoming part of product discovery

We usually think of documentation as something people read after choosing a plugin: discover, compare, buy, install, read docs. With an agent involved, documentation can become part of the selection itself. The agent might need to answer “can this plugin programmatically change Schema for a custom post type” before FictionalWPSEO is ever purchased. Good public documentation serves two stages: before purchase, can this plugin solve my problem, and after purchase, how do I implement it correctly.

What FictionalWPSEO’s docs might look like today

Say we launched with:

/docs/
    getting-started/
    settings/
    developers/
    troubleshooting/

Not terrible, but look what happens when someone wants to know how to change an SEO title from PHP. They open Developers, and that page contains PHP examples, hooks, filters, REST endpoints, custom Schema, sitemap customization, WooCommerce examples, and troubleshooting notes, all mixed into one 7,000 word page. Humans have to search through it. A retrieval system has to identify the relevant section inside a document covering several unrelated concepts.

Give each important concept its own page

I’d restructure it closer to:

/docs/
    getting-started/
        installation/
        requirements/
        activation/
        quick-start/
    seo-metadata/
        titles/
        descriptions/
        canonical-urls/
        robots/
    sitemaps/
        overview/
        custom-post-types/
        exclude-content/
        filters/
    schema/
        overview/
        article/
        product/
        custom-schema/
        developer-api/
    woocommerce/
        overview/
        product-seo/
        product-schema/
    redirects/
        creating-redirects/
        managing-redirects/
        developer-api/
    developers/
        php-api/
        hooks/
        filters/
        rest-api/
        authentication/
        examples/
    troubleshooting/
        common-errors/
        plugin-conflicts/
        debugging/

Now there’s a predictable location for a given question. “How do I customize Product Schema” points to /docs/schema/product/. “How do I modify SEO metadata using PHP” points to /docs/developers/php-api/. This helps humans navigate, and it produces smaller, semantically focused documents that are easier for retrieval systems to match against a question.

Page titles should answer real questions

“Developer Options” tells you nothing. “Modify WordPress SEO Metadata Using PHP” tells you a lot. Same with “Advanced Settings” versus “Exclude Custom Post Types from XML Sitemaps,” or “WooCommerce Integration” versus “Customize WooCommerce Product SEO Metadata” and “Modify WooCommerce Product Schema.” Not about stuffing keywords in headings, it’s about removing ambiguity. A good title should make sense on its own, without the surrounding navigation.

One page, one problem

A page called “Modify SEO Metadata Using PHP” should stick to that task. Don’t fold in “how to configure XML sitemaps” halfway down just because it’s another developer feature; make a new page. That gives you a straight line from question to specific page to explanation to working example to expected result, rather than question to huge page to hunting through unrelated sections to maybe finding the answer. This matters even more once documentation is being retrieved automatically rather than browsed.

Start with a direct answer

On a page titled “Modify SEO Metadata Using PHP,” I wouldn’t open with “FictionalWPSEO is a powerful and flexible WordPress SEO solution designed to give developers complete control…” The visitor is already in the docs. Get to the point:

FictionalWPSEO provides the fictionalwpseo_update_meta() function for updating SEO metadata programmatically. It can update the SEO title, meta description, canonical URL and robots settings for supported content types.

Then the simplest possible example:

fictionalwpseo_update_meta(
    $post_id,
    [
        'title'       => 'Custom SEO Title',
        'description' => 'Custom meta description.',
    ]
);

Within seconds, both a developer and an agent understand the basic interface.

Explain every example

Code alone isn’t enough. Say the doc shows:

fictionalwpseo_update_meta(
    $post_id,
    [
        'title'       => 'Luxury Apartments in Chandigarh',
        'description' => 'View available apartments, prices and floor plans.',
    ]
);

Right below it, say what happens:

This updates the SEO title and meta description for the post represented by $post_id. Existing canonical URL, robots and Schema settings are not changed.

That second sentence matters. Now the agent knows this is a partial update, not a full replace.

Document parameters explicitly

Don’t make developers reverse-engineer parameters from a single example.

Then document what it returns: true on success, WP_Error if the post doesn’t exist, the content type isn’t supported, or the metadata fails validation. Now the agent doesn’t have to guess.

Show error handling too

Most documentation only shows the happy path. An agent generating production code needs the failure mode as well:

$result = fictionalwpseo_update_meta(
    $post_id,
    [
        'title' => 'Luxury Apartments in Chandigarh',
    ]
);

if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_message() );
}

That teaches the correct integration pattern instead of just the shortest possible snippet.

Use complete WordPress examples

Context matters. Instead of only fictionalwpseo_update_meta( $post_id, $data );, show a real workflow. Say we want SEO metadata generated automatically when a property custom post type is saved:

add_action(
    'save_post_property',
    function ( $post_id, $post, $update ) {

        if ( wp_is_post_revision( $post_id ) ) {
            return;
        }

        fictionalwpseo_update_meta(
            $post_id,
            [
                'title' => sprintf(
                    '%s | Properties for Sale',
                    get_the_title( $post_id )
                ),
            ]
        );
    },
    10,
    3
);

Now the example shows how FictionalWPSEO fits into an actual WordPress workflow, which is a lot more useful than the function documented in isolation.

Give examples real names

I’d also skip foo, bar, example, test. Documentation reads better when examples resemble real projects: property, event, book, course, product. “Add Product Schema to WooCommerce products.” “Exclude the event post type from the sitemap.” “Generate SEO titles for property posts.” These communicate intent immediately.

Document hooks properly

WordPress developers rely on actions and filters. If FictionalWPSEO provides apply_filters( 'fictionalwpseo_meta_title', $title, $post_id ), don’t just list the hook name. Document it properly:

fictionalwpseo_meta_title

Filters the final SEO title before FictionalWPSEO outputs it in the document <head>.

Parameters$title (string): current SEO title.
$post_id (int): current post ID.

Returns
(string) filtered SEO title.

Then an example:

add_filter(
    'fictionalwpseo_meta_title',
    function ( $title, $post_id ) {

        if ( 'property' === get_post_type( $post_id ) ) {
            return $title . ' | Property Listings';
        }

        return $title;
    },
    10,
    2
);

Now the agent can use the hook correctly without inventing parameter names.

Don’t forget version information

APIs change. If an agent finds a three year old tutorial using fictionalwpseo_set_meta() but version 3 uses fictionalwpseo_update_meta(), which should it use? Say so directly:

fictionalwpseo_update_meta()
Available since FictionalWPSEO 3.0. Replaces the deprecated fictionalwpseo_set_meta().

And on the old page: “Deprecated since 3.0. Use fictionalwpseo_update_meta() instead.” Not just an AI problem, but AI generated code makes outdated examples more visible, since models and search systems encounter material published across many versions.

Keep documentation URLs stable

If /docs/php-api/ gets linked from hundreds of articles and then a redesign moves it to /developer/resources/php/functions/ without a redirect, every external reference breaks. Stable URLs have real value for documentation. If you have to restructure, redirect the old ones properly, and treat headings the same way when other pages link directly to sections.

Make documentation public where possible

FictionalWPSEO is paid, but that doesn’t mean developer documentation should sit behind a customer login. There may be good reasons to restrict support resources or downloads, but documentation explaining features, APIs, hooks, filters, integrations, compatibility and examples has value before purchase. If the doc answering “can FictionalWPSEO programmatically modify Product Schema” is behind a login, an agent evaluating the plugin may never see it. The code stays commercial. The documentation can stay public.

Use normal HTML

I’d avoid making critical documentation depend on a complicated JavaScript interface. Fancy search and interactive examples are fine, but the underlying content should be clean, crawlable HTML with sensible semantic structure, headings, code blocks, and paragraphs actually present in the page source. Nothing exotic required. Good web fundamentals still matter.

Link related concepts together

If someone’s reading “Modify WooCommerce Product Schema,” useful related links might be the Product Schema reference, the WooCommerce SEO overview, the PHP API, Schema filters, and a complete WooCommerce example. That turns documentation into a connected knowledge base instead of isolated pages, which helps navigation for developers and helps systems understand how concepts relate.

Create a dedicated examples section

I’d give FictionalWPSEO a full section of real examples:

/docs/examples/
    generate-seo-title-on-save/
    custom-post-type-seo/
    property-schema/
    woocommerce-product-schema/
    exclude-posts-from-sitemap/
    create-redirect-programmatically/
    modify-open-graph-image/

Each explaining the goal, requirements, complete code, how it works, expected result, and security or performance considerations where relevant. Useful for developers, and it gives coding agents high quality implementation patterns to work from.

Avoid contradictory documentation

As a plugin grows this gets harder. The product page says PHP 8.0+, the installation page says 8.1+, last year’s blog post says 7.4+, the FAQ says “supports all modern PHP versions.” Which is right? Humans get confused, agents do too. I’d establish a small set of canonical facts, the current version, WordPress requirement, PHP requirement, WooCommerce requirement, license structure, supported APIs, supported integrations, and keep them consistent everywhere. Ideally these come from one data source rather than being copied into twenty pages by hand.

Documentation needs maintenance just like code

Say FictionalWPSEO 4.0 removes a filter. Updating the PHP isn’t enough; the API reference, hook documentation, examples, migration guide, changelog and related tutorials all need to change too, or your public documentation describes a product that no longer exists. If agents are relying on it, accuracy matters even more. Outdated documentation doesn’t just generate support tickets. It generates incorrect code.

A simple documentation template

For functions: name, what it does, available since, syntax, parameters, return value, basic example, complete example, error handling, related functions, related hooks, known limitations.

For hooks: name, action or filter, when it runs, parameters, return value if a filter, example, available since, related hooks.

For features: what it does, when to use it, requirements, configuration, developer API, examples, limitations, troubleshooting, related documentation.

Predictable structure is worth it. Once someone understands one page, they understand how to navigate the rest.

Notice what we haven’t done yet

FictionalWPSEO still doesn’t have anything exotic. No AI API, no MCP server, no special files telling AI systems about the site. We’ve done something more basic: written really good developer documentation, with machine consumption in mind. Public, specific, structured, predictable, internally linked, versioned, example-driven, explicit about limitations, on stable URLs, available as normal HTML. That matters because before creating files specifically for coding agents or LLM-based systems, we need something worth pointing them at.

The next problem

Now imagine an agent is actually working inside a WordPress project where FictionalWPSEO is installed. It opens the project and sees wp-content/plugins/fictionalwpseo/, woocommerce/, my-custom-plugin/. How does it know the preferred way to interact with FictionalWPSEO? Which public APIs to use? Which internal classes to avoid? What coding conventions matter? Where the docs live? Are there security rules to follow? That’s where one particular file starts to matter.

Next: Should Your WordPress Plugin Have an AGENTS.md?