Why Your AI Documentation Workflow is Probably Creating Technical Debt

A few months back, a client came to me with a classic mess. They had a massive custom WooCommerce extension—thousands of lines of logic—and zero documentation. Their lead dev had left, and the new team was flying blind. In a fit of desperation, they’d tried to “fix” it by pointing an LLM at the codebase and asking it to write a manual. Total disaster. The AI hallucinated hooks that didn’t exist and suggested filters that would have crashed the site on activation. It was technical debt wrapped in a confident-sounding lie.

I’ll be honest: my first thought was to just do the same thing but “better.” I figured if I fed the code into a higher-tier model with a bigger context window, I’d get a perfect README. I was wrong. Without a strict AI documentation workflow and a human reality check, you’re just generating noise. You can’t just dump code and expect a manual; you need a framework that understands the WordPress way of doing things.

The Right Way to Build an AI Documentation Workflow

The core team is actually tackling this right now for the WordPress 6.9 release cycle. I’ve been following the discussion over at the Make WordPress AI blog, and they hit the nail on the head. The goal isn’t to replace the dev; it’s to augment them. You use AI to generate the structure and the first draft based on specific style guides, but a human stays in the driver’s seat for fact-checking.

If you’re trying to document a complex project, don’t just ask the AI to “explain this code.” Instead, give it the specific parameters it needs to look for. I usually start by programmatically extracting the relevant metadata so the AI isn’t guessing. Here’s a simple helper function I use to pull hook names and descriptions from a file before I even think about writing a prompt.

function bbioon_extract_hook_metadata( $file_path ) {
    if ( ! file_exists( $file_path ) ) {
        return [];
    }

    $content = file_get_contents( $file_path );
    $hooks   = [];

    // Simple regex to find apply_filters and do_action
    preg_match_all( '/(apply_filters|do_action)\s*\(\s*[\'"]([^\'"]+)[\'"]/', $content, $matches );

    if ( ! empty( $matches[2] ) ) {
        foreach ( $matches[2] as $index => $hook_name ) {
            $hooks[] = [
                'type' => $matches[1][$index],
                'name' => $hook_name,
            ];
        }
    }

    return $hooks;
}

This is the “Responsible AI” part. You aren’t asking the machine to be creative; you’re asking it to be organized. By feeding it the actual hook list extracted via PHP, you prevent the “imaginary hook” problem that kills trust in your documentation. This is exactly what the proposal for 6.9 is aiming for—structured, verifiable drafts that stick to the official style guides.

Documentation as Insurance, Not a Chore

Look, I get it. Writing docs feels like a waste of time when you could be shipping features. But as a senior dev, I’ve seen how much money is burned when a team has to spend three days reverse-engineering a “clever” function because nobody wrote down what it does. Using an AI documentation workflow effectively turns a 10-hour chore into a 1-hour editing session. Just don’t skip the editing part. Period.

The future of WordPress dev isn’t about avoiding AI; it’s about not being lazy with it. If you treat AI like a junior intern who needs very specific instructions, it’s a powerhouse. If you treat it like a magic “fix everything” button, you’re going to have a bad time. Trust me on this.

Look, this stuff gets complicated fast. If you’re tired of debugging someone else’s mess and just want your site to work, drop my team a line. We’ve probably seen it before.

Ahmad Wael

See Full Bio