Reporting an issue

The Documentation team is in charge of several different projects across WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://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. GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ (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. SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/ (#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 metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. 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, BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor, Common APIs, and Plugins are maintained by the Documentation team. 

Code Reference

Code Reference is divided into three parts:

• Inline docs
• More Information
• User Notes

Inline Docs

Because of how it is created, Inline Docs is currently maintained by the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/index.php syntax highlighting, use a shortcodeShortcode A shortcode is a placeholder used within a WordPress post, page, or widget to insert a form or function generated by a plugin in a specific location on your site. 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.