WordPress has hit a real milestone in the WordPress Documentation overhaul, and it is overdue. If you have ever burned three hours on a legacy filter before noticing that the DevHub entry was last touched when PHP 5.6 was current, you know how far the docs have drifted. The Documentation Team has now triaged nearly 800 issues and closed more than 200 of them in the last few months.
Why the parser issue is killing your workflow
A lot of the outdated developer documentation traces back to what the team calls a “parser issue.” WordPress generates the code reference at developer.wordpress.org with WP-Parser, which scrapes the codebase, reads the DocBlocks, and turns them into the searchable UI everybody uses. When the parser breaks, or when inline documentation strays from the expected format, DevHub quietly falls out of sync with core.
This WordPress Documentation overhaul goes after those broken links and stale code snippets. With the WordPress 7.0 roadmap coming up, a reliable source of truth is closer to a requirement than a bonus, since the performance and security guidance on those pages is what people copy into production.
The correct way to document a filter
If you are contributing to this WordPress Documentation overhaul, remember that the parser is fussy about format. This is what a properly documented hook looks like:
/**
* Filters the metadata for a specific post type.
*
* @since 1.2.0
*
* @param array $metadata The array of metadata values.
* @param int $post_id The ID of the post being processed.
* @param string $context The context in which the filter is called.
*/
$metadata = apply_filters( 'bbioon_custom_post_metadata', $metadata, $post_id, $context );Where the help is needed most
The Documentation Team has named the areas where it is short-handed. If you know any of these well, that experience goes further here than it does on most open issues:
- Themes Handbook, 146 open issues, mostly block theme documentation and outdated hybrid theme tutorials.
- DevHub, 101 open issues, covering the parser-generated reference and code examples that need updating for modern PHP.
- HelpHub, 358 open issues, end-user documentation for a Block Editor interface that keeps changing under it.
I wrote earlier about the restoration of documentation for older versions. This WordPress Documentation overhaul is a bigger swing, aimed at the cause of the rot instead of patching pages one at a time.
If documentation and technical debt are eating your dev hours, I can take it off your plate. I have been working with WordPress since the 4.x days.
Takeaway: better docs, better sites
Documentation is how a feature reaches the people who have to build with it. When the explanation is wrong, the implementations come out wrong too, and they stay wrong for years. Closing stale issues on the official GitHub tracker counts for that, and so does drafting new markdown; either way the next person reading the Code Reference gets a better answer. Around 600 issues are still open.
