The Documentation team is in charge of several different projects across WordPress.org. These projects use different tools for contributing, and therefore, the workflow for reporting an issue varies depending on the project.
This page is mainly for one-time and first time contributors. So, if you are just starting contributing to the Documentation team or you just want to report an issue you came across, this page should provide an easy-to-follow step-by step guide on how to do so.
You can report documentation issues in two ways:
1. GitHub (recommended)
Create an issue in the Documentation Issue Tracker:
https://github.com/WordPress/Documentation-Issue-Tracker/issues
This is the primary method for tracking and resolving documentation issues.
2. Slack (#docs channel)
You can also ask questions or discuss issues in the WordPress Slack #docs channel.
If you’re not yet a member, you can join here: https://make.wordpress.org/chat/
For clarity and tracking, using GitHub Issues is recommended for reporting documentation issues.
If you do not have access to Make WordPress Slack, please see this guide.
HelpHub
HelpHub is a working title for end user documentation located at https://wordpress.org/documentation/. If you found an issue in an article there, here’s how to report it.
Content issue
If you find a typo, outdated or incorrect information, broken links, outdated screenshots, missing images, or any other content-related issue, please follow these steps:
- Go to the GitHub repository and check the existing issues to see whether anyone has already started a discussion: https://github.com/WordPress/Documentation-Issue-Tracker/issues.
- If not, open a new issue. Click New issue and select an appropriate template, such as:
- Fix Doc Issue Report … for reporting a new issue
- New Doc Request … for requesting a new page
Development issue
You found an article with a broken layout or similar issues affecting how the content is displayed.
Reporting a development issue:
- Go to meta Trac and check the existing HelpHub tickets to see whether anyone has already reported the issue – https://meta.trac.wordpress.org/query?status=!closed&component=HelpHub
- If not, select “New Ticket”
- Select the “HelpHub” component from the dropdown
- Make sure the “Summary” field clearly describes the issue
- In the “Description” field, describe the problem with as much detail as possible (links and screenshots are welcome). If possible, the description should follow the template:
- Expected behavior
- Actual behavior
HelpHub development is maintained by Milana Cap.
DevHub
DevHub is a working title for all developer documentation, a set of Handbooks located at https://developer.wordpress.org/. Not all projects (Handbooks) here are the responsibility of the Documentation Team. The REST API, WP-CLI, and WordPress Coding Standards Handbooks are maintained by their respective teams.
The Themes Handbook is a shared responsibility of the Documentation and Theme Review teams. Everything else: Code Reference, Block Editor, Common APIs, and Plugins are maintained by the Documentation team.
Code Reference
Code Reference is divided into three parts:
Inline Docs
Because of how it is created, Inline Docs is currently maintained by the Core Team, but it is still considered documentation. Read more about Inline docs in the Core team’s Handbook.
Report the issue:
- Go to Core Trac and check among existing tickets if anyone has already reported the issue – https://core.trac.wordpress.org/query?status=!closed&focuses=~docs
- If not, open a new ticket with the docs focus
- Select the appropriate component from the dropdown
- If you have never opened a Trac ticket before, here’s a detailed guide – https://make.wordpress.org/core/handbook/tutorials/trac/opening-a-ticket/
- Make sure the “Summary” field clearly describes the issue
- In the “Description” field, describe the problem with as much detail as possible (links and screenshots are welcome)
More Information
This section appears right between the “Related” and “User Contributed Notes” sections. Its purpose is to further explain the code and its usage. It is not meant for code examples. This is what User notes are for.
For now the only way to report the issue is to post it in #docs slack channel.
The More Information section is maintained by Julio Potier.
User Notes
User Notes are code snippets and examples of how to use the function, class, method, or hook in question. They work exactly the same as comments.
Post your example as you would post a comment. It will be held under moderation until it’s reviewed by the Docs team. For proper PHP syntax highlighting, use a shortcode to wrap your code example:
[php][/php]To report an issue with any of the already published notes, use the “Add feedback to this note” link. It is located right below the example and behaves as a reply to the comment. Just as the note itself, it will also be held for moderation.
Once you have reported an issue or posted your code example, please be patient. It is uncertain how much time we’ll need to review it, as it depends on the current queue and how many Docs team members are available to work on it at that moment. You are always welcome to join the team and help with User Notes.
User Notes are maintained by Jb Audras and Leo Germani.
Block Editor Developer’s Handbook
Documentation for developing on top of or with the block editor lives on GitHub, from where it is parsed to our Block Editor Handbook.
For contributing to Block Editor documentation, please refer to this document.
Report the issue with the Block Editor’s documentation:
- Make sure the issue is not already open by checking all the Docs issues on GitHub,
- If no one reported it, open a new issue.
Documentation for developing with and on top of Block Editor is maintained by Paul Barthmaier.
Common APIs Handbook
Reporting issues found in this Handbook is done in the #docs Slack channel.
The Handbook for Common APIs is maintained by Leo Germani.
Plugin Developer’s Handbook
Reporting issues found in this Handbook is done in the #docs Slack channel.
The Handbook for developing a plugin is maintained by theMikeD.
Theme Developer’s Handbook
The Handbook for developing a theme is shared responsibility between the Documentation and Theme Review teams. While we are happy to fix any issues found in this Handbook, we would recommend reporting issues to its Rep, Ana Alfieri from the Theme Review team, directly in #themereview Slack channel.
Documentation Team Handbook
If you find an issue in this handbook, please report it in the Documentation Issue Tracker on GitHub.
If you have questions before reporting it, you can ask in the #docs Slack channel.
This Handbook is maintained by Akira Tachibana and Milana Cap.