Welcome to the official home of the WordPress Documentation Team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the handbooks and other general wordsmithing across the WordPress project.
Want to get involved?
Start here to find out more about what we do and how to contribute:
Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub 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/
Weekly meetings
Join our discussions of documentation issues here on the blog and on Slack.
While writing and updating HelpHub articles for 6.9, the team discovered that many articles have not been updated making it difficult to maintain the quality of the documentation. For this reason, the team is incurring in an overhaul of the documentation with 3 main goals:
Improve the quality of the documentation.
Use the changelog to recognise contributors.
Update the blocks articles before WP 7.0 is released.
What is the overhaul and how it works
A project has been created in GitHubGitHubGitHub 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/ for each of the categories plus the blocks – see links below. In each categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. there is a READ FIRST issue with instructions.
Basically, a new issue is open per blockBlockBlock 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./feature with the title “Overhaul XX block documentation”. Look at the related open issues, see what’s still useful, and close anything that’s ancient/irrelevant. For other details, follow the instructions in the READ FIRST article.
Key things to remember:
Self-assign the issue you decide to tackle.
Close those outdated issues! Don’t let them hang around.
Write your final updates in the comments first, before you update the actual article in WordPress.
Need to edit the docs site? PingPingThe 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.”@estelaris or @milana_cap for access.
Don’t forget the contributors! Add anyone who suggested something (even if you don’t use it) to the changelog. You only need to contribute once to become a Docs contributor!
If you can’t figure out a contributor’s WordPress username, just ask in the SlackSlackSlack 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.
Note: if there is only one issue open for a feature/block, only the title has been edited to add the word “Overhaul”. This is done to avoid extra issues and extra work.
The list of the overhaul projects in GitHub:
Note: the audit on the GH docs issue tracker is still happening, thus projects below will be updated as soon as possible.
@atachibana is working on the Grid blockBlockBlock 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., issue 1615.
Finish uploading 6.5 articles (they are ready just need to update WordPress)
Rethink a “discussion for a proposal for the “wiki-like” update on documentation (FYI, this is going to affect all the documentation throughout wp.org). There are several items to think about: automated translation, how we can integrate GitHubGitHubGitHub 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/ in a way that doesn’t involve the user (only the people updating the documentation), and how to notify changes.
Work on the mobile documentation (get it ready for screenshots)
Regarding this, @vishal4669 started working on the Mobile Documentation and completed issues 1609, 1608, and 1606.
There needs to be another design update on HelpHub but we are still on hold until I finish a proposal to make some changes to the sitemap.
Open Floor
@vishal4669 asked if for the 6.6 HelpHub tickets he should update the issues like he’s doing it for the mobile documentation. @atachibana replied that if the modifications are small, they can be written in GitHub. As on issue 1617. But if it’s a large amount, it’s better to write it in a Google Document and share the link.
@sagargurnani refers to a comment on today’s agenda, regarding the broken images on the posts. Following the agreements in that regard:
Everyone who has access to update the article on WP should be notified that the images should be reuploaded into the WP image library to avoid broken images.
This should be mentioned in the “General Section” of the issues.
There’s an issue with articles that have broken/missing screenshots: 1649.
The message that has to be added to the general section is “Upload the images/videos into the WP image library to avoid broken images”. It should be included in the new issues template.
Goal: Create a plan of how to move forward with the localization/translation of documentation project
Discussion: Cross-team communication
Discussion: What does GlotPress need to move forward. GlotPress has a translation memory, but it’s not context-aware. This makes automated reuse of shorter strings harder.
Discussion: Can we use GH as a docs issue tracker, in the same way global does it? Or can we take advantage of the global docs issue tracker and create labels for languages? How are other teams doing it? Spanish team started with this: https://github.com/orgs/WordPress/projects/195
Request: What does metaMetaMeta 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. need to prepare Rosetta sites for the documentation page, First discussion: https://meta.trac.wordpress.org/ticket/7637
During the contributor dayContributor DayContributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. at WordCampWordCampWordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Torrelodones 2024, the Spanish documentation team started the translation for the end-user documentation.
The initial objectives were:
Decide the day and time for the weekly team meeting
Define responsibilities for meeting facilitators
Technical requirements for a documentation team member
How to effectively coordinate with the Spanish translation team
Review the Style Guide for translation
Define the translation process
Suggest new words to the Spanish (Spain) Glossary
Conclusions of the Spanish documentation team
Weekly meetings
The team is already meeting on Fridays at 09:00 UTC in the Spanish Slack channel#documentacion. The first meeting will take place on Friday 5 April 2024
The meetings will be announced in the Spanish SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/., same way as the global team does
Responsibilities for meeting facilitators
The team agreed that @estelaris will run the first few meetings and then it will be rotated among contributors
Whoever runs the meeting must prepare the agenda based on the previous meeting
Contributor technical requirements
Know sufficient English to understand the content that is being translated
Basic understanding of GitHubGitHubGitHub 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/
Translation Style Guide
Another goal is to improve the Spanish Style Guide to be able to write the documentation, following the rules already instilled by the translation team. This work will be based on the Documentation Style Guide written by the global team. Follow the work in GitHub Spain Handbook #288.
Translation process
The translation process the team will follow includes:
Update the style guide and have it reviewed and approved by the translation team
Prioritize articles for translation (high, medium, low) as well as add tasks to the issues (content, screenshots, videos, etc)
Work with #meta team to open the es.wordpress.orgWordPress.orgThe 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//documentacion site
Translate the articles and pass them to the Spanish polyglots teamPolyglots TeamPolyglots Team is a group of multilingual translators who work on translating plugins, themes, documentation, and front-facing marketing copy. https://make.wordpress.org/polyglots/teams/. for review
Make the documentation available in Spanish from Spain as soon as the site is set
This post will be updated accordingly and it is a translation of the post in Make Spain Blog.
props to @josepmoran for taking notes during contributor day and to help write this post in Spanish
Please review the issues here as the team will be discussing them during the meeting on March 5.
Consider adding introduction to what is included in the documentation site
The conversation can be followed in GitHub. The proposal is to add a tagline to the headerHeaderThe header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and there are some good proposals there. This needs to be decided quick as the metaMetaMeta 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. team is getting ready to finish the redesign.
Documenting the Playground for end-users
@zieladam has some ideas to include Playground documentation in HelpHub. The idea is to create use cases for now.
The use cases and recommendations are written in the User Documentation ticket in the GH Playground. Once a docs contributor is interested in working on these articles, we can transfer them to the docs/issue GH.
The Docs team needs your help to update and revise the End User Documentation (HelpHub) for the upcoming WordPress 6.4 release, expected on November 7, 2023.
You can find a list of all the tasks in the 6.4 project board in the Documentation repository on GitHubGitHubGitHub 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/.
Add a comment on the GitHub issue you would like to work on, and someone on the Docs team will assign it to you.
Once a task is assigned to you, the following two videos show how to help with updating the existing articles in End User Documentation (HelpHub).
Video introduction: contributing to End User documentation Video showing how to help with updating the existing articles on GitHub (this uses 6.2 as an example).
Once you complete the updates for the particular task, add a comment to the issue you were working on:
with a note on the changes you made
and tag the following contributors in the Docs team (on the Make WordPress SlackSlackSlack 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 add ‘@’ before the ID: femy, LeonardusNugraha, or jenni)
a contributor from the Docs team will be able to review the updates and add the content to the article
If you have questions or need help, ask in the docs channel on the Make WordPress Slack or directly in the GitHub issue itself.
If your meetupMeetupAll local/regional gatherings that are officially a part of the WordPress world but are not WordCamps are organized through https://www.meetup.com/. A meetup is typically a chance for local WordPress users to get together and share new ideas and seek help from one another. Searching for ‘WordPress’ on meetup.com will help you find options in your area., collective or organization can give a blockBlockBlock 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. of time to help, leave a comment on this post or send a message to the documentation channel on the Make WordPress Slack and include the Release co-leads for 6.4 documentation in your message: (add ‘@’ before the ID) @abhanonstopnewsuk, @Femy, @611shabnam.
Resources
If you need a test site with WordPress 6.4 pre-installed, you can use this app providedby InstaWP to spin up a new temporary website. It is preloaded with Theme Test data and other pre-configuration and is ready to go. This new site will be available to use for four hours. After that, if you need another test site to contribute to docs, you can visit the link again and create a new temporary site.
When revising already published content on HelpHub, you can use the RevisionsRevisionsThe WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. Extended pluginPluginA plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party that is already installed. Refer to the video: How we use the Revisions Extended plugin on Learn WordPress.
Where can I find other documentation on the 6.4 release?
The release group with other coreCoreCore is the set of software required to run WordPress. The Core Development Team builds WordPress. and doc contributors have been working on developer notes related to major features and changes in 6.4. The Field Guide for WordPress 6.4 is available and brings together the most important items. You can also view all dev notes via the 6.4 developer notes tag.
Props to @webcommsat for input into this post and its review.
As you may know, the Documentation team is starting a collaboration with other teams, mainly Polyglots, in translating complete end-user documentation (HelpHub). This documentation and its many translations will have a new place to live: GitHubGitHubGitHub 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/ repository WordPress/documentation-end-user.
Before we start translating, we must move all existing docs to the repo. After that is done, all translations, as well as creating new documentation in English and updating the existing one, will happen in that same repository.
This means a lot of new contributors, new contributor roles, different workflows, and different processes… Rather than letting the mess dictate our repo settings and workflows, let’s try to use our experience with Issue Tracker and predict possible problems and needs.
As a starting point, let’s identify different user roles contributing to the end-user docs repo and what would make their contributions easier and more streamlined.
All the issues are created as user stories and are only concerned with a single problem.
At this point, there are the following settings in the project. These might be incomplete and/or wrong, which we will know in time.
Persona
First-time contributor
Experienced contributor
Repo maintainer
Issues coordinator
First-time reviewer
Experienced reviewer
Translator
Translation editor
Any contributor
The life cycle of an issue
Creating issue
Updating screenshots
Creating new documentation
Reviewing issue
Managing issue
Working on issue
Type of workflow
Automation
Manual
Template (issue and pull request)
The end result of this effort should give us the idea of the following:
How the issue/pull request is named – template
What is the structure of the issue/pull request
The list of labels with descriptions and explanations of when to use them
Automated tasks
The life cycle of the issue/pull request
Well-defined user roles and their responsibilities
Feel free to start adding new stories and keep in mind to focus on a single problem per issue.
The Docs team needs your help to update and revise the End User Documentation (HelpHub) for the upcoming WordPress 6.3 release, expected on August 8th, 2023.
You can find a list of all the tasks in the 6.3 project board in the Documentation’s repo on GitHubGitHubGitHub 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/.
Add a comment on the GitHub issue you would like to work on, and someone on the Docs team will assign it to you.
Once a task is assigned to you, the following two videos show how to help with updating the existing articles in End User Documentation (HelpHub).
Video onboarding to End User documentation Video showing how to help with updating the existing articles on GitHub (referencing 6.2 in this video)
Once you complete the updates for the task, add a comment to the issue you worked on, noting that you have made the changes, and tag the Docs team (@femkreations, @Leonardus-Nugraha or @jennimckinnon). Someone from the Docs team will review the updates and add the content to the article.
If you have questions or need help, ask in the docs channel on the Make WordPress SlackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. or directly in the GitHub issue itself.
If your meetupMeetupAll local/regional gatherings that are officially a part of the WordPress world but are not WordCamps are organized through https://www.meetup.com/. A meetup is typically a chance for local WordPress users to get together and share new ideas and seek help from one another. Searching for ‘WordPress’ on meetup.com will help you find options in your area. or company can give a blockBlockBlock 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. of time to help, do include the Release co-leads for 6.3 documentation in your message: (Slack IDs) @Femy, @Leonardus Nugraha, @611shabnam.
Resources
If you need a test site with WordPress 6.3 pre-installed, you can use this app providedby InstaWP to spin up a new temporary website set. It is preloaded with Theme Test data and other pre-configuration, ready to go. This new site will be available to use for four hours. After that, if you need another test site to contribute to docs, you can visit the link again and create a new temporary site.
The docs team is preparing to integrate the Mobile app end-user documentation into HelpHub. Since it wasn’t available at the time when the new sitemap was created, looking for a place for it is not easy.
At the moment, the Mobile App is split into 6 categories, mostly written in the FAQ format.
All links – broken, outdated and find replacements
Content – still relevant, has anything changed in the last version?
Images – need new screenshots?
Features – are there new features that are not documented yet?
New issues – are we missing documentation for any other issue?
Classification
The team is also reviewing the classification to find a better pattern for users. Since the articles are written in an FAQ form, perhaps some articles can be rewritten in the new template as “feature description + how it works.”
During the recategorization of the documentation, the team removed several articles that were developer-focused or included a lot of developer-jargon. All these articles are now part of the Advanced Administration Handbook and will be removed from /documentation/devhub/.
The redirects have been applied as indicated in issue #59. Some articles have been merged to provide better explanations. Although, the maintenance is still ongoing, most of the articles have been updated.
