Reporting an issue

Documentation team is in charge of several different projects. These projects use different tools for contributing and, therefore, reporting an issue has different workflow 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.

The easiest way to report any kind of documentation issue is to go to #docs 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/. channel and just post. If you know which Docs project is this issue in, you can even pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” the person responsible for it. See all our reps on our team page.

HelpHub

HelpHub is a working title for end user documentation located at https://wordpress.org/support/. If you found an issue in an article there, here’s how to report it.

Top ↑

Content issue

You found a typo, outdated or incorrect information or screenshots, broken links or images, or any content related issue. 

Note: We plan to enhance reporting an HelpHub content issue workflow with unique experience of reporting it directly on the article where the issue is found. Until this is applied, we have two separate workflows. 

Non 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 content is maintained by Akira Tachibana

Reporting an issue for existing content:

  • Go to 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 be the repository owner. https://github.com/ repo and check among existing issues if anyone has already started discussion – https://github.com/WordPress/HelpHub/issues
  • If not, open new issue with:
    • assignee: atachibana
    • label: bug

Requesting new content:

Any block editor related content is maintained by Birgit Pauli-Haack

Reporting block editor end user documentation issue:

Top ↑

Development issue

You found an article with broken layout or any similar unexpected behavior in rendering the content.

HelpHub development is maintained by Milana Cap.

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 among existing HelpHub tickets if anyone has already reported the issue – https://meta.trac.wordpress.org/query?status=!closed&component=HelpHub
  • If not, select “New Ticket”
  • Select “HelpHub” component from the dropdown
  • Make sure that “Summary” field does summarize the issue
  • In the “Description” field describe the problem with as much detail as possible (links and screenshots are welcome). If possible, description should follow template:
    • Expected behavior
    • Actual behavior

Requesting a feature:

  • Go to GitHub repo and check among existing issues if anyone has already started discussion – https://github.com/WordPress/HelpHub/issues
  • If not, select “New Issue”
    • assignee: zzap
    • label: enhancement
  • Make sure that “Title” field summarize the feature
  • In the “Description” field describe the feature with as much detail as possible (links and screenshots are welcome). If possible, description should follow template:
    • Description of the feature
    • How is this feature enhancing the documentation and user’s experience?

Top ↑

DevHub

DevHub is a working title for all developer’s documentation, a set of Handbooks located at https://developer.wordpress.org/. Not all projects (Handbooks) here are under Docsumentation’s team responsibility. REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/., WP-CliWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ and WordPress Coding StandardsWordPress Coding Standards The Accessibility, PHP, JavaScript, CSS, HTML, etc. coding standards as published in the WordPress Coding Standards Handbook. May also refer to The collection of PHP_CodeSniffer rules (sniffs) used to format and validate PHP code developed for WordPress according to the PHP coding standards. Handbooks are maintained by their respective teams. 

Themes Handbook is a shared responsibility between Documentation and Theme Review teams. Everything else: Code Reference, Block Editor, Common APIs and Plugins are maintained by the Documentation team. 

Top ↑

Code Reference

Code reference is divided into 3 parts:

Top ↑

Inline Docs

Because of the nature of creation, Inline Docs is maintained by the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. team for a while now but it is still documentation. Read more about Inline docs in Core team’s Handbook.

Report the issue:

Top ↑

More Information

This section appears right between “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.

The More Information section is maintained by Julio Potier.

For now the only way to report the issue is to post it in #docs slack channel.

Top ↑

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 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. http://php.net/manual/en/intro-whatis.php. syntax highlighting use 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 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.

Top ↑

Block Editor Developer’s Handbook

Documentation for developing on top or with 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 Block Editor’s documentation: 

Documentation for developing with and on top of Block Editor is maintained by Paul Barthmaier.

Top ↑

Common APIs Handbook

The Handbook for Common APIs is maintained by Leo Germani. Reporting issues found in this Handbook is done in #docs Slack channel.

Top ↑

Plugin Developer’s Handbook

The Handbook for developing a plugin is maintained by theMikeD. Reporting issues found in this Handbook is done in #docs Slack channel.

Top ↑

Theme Developer’s Handbook

The Handbook for developing a theme is shared responsibility between Documentation and Theme Review team. While we are happy to fix any issues found in this Handbook, we would recommend reporting issues to its Rep, Ana Alfieri from Theme Review team, directly in #themereview Slack channel. 

Top ↑

Documentation Team Handbook

This Handbook is maintained by Akira Tachibana and Milana Cap. If you have found any issues here please report it in #docs Slack channel.

Last updated: