Welcome to the official home of the WordPress documentation team.
This team is responsible for all things documentation, including the Codex (moving to HelpHub), handbooks, developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.
Want to get involved?
We need your help keeping content current with each WordPress release and adding new content and screenshots to:
One of the goals for the redesign of the documentation in WordPress.org is to create a better search. The best way to do it is by reclassifying all the articles and creating categories with subcategories.
In discussions with the #docs team, we agreed that the best option to do this was by working with a group of people that included developers, documentation, designers and content specialists.
Our goals for the working session were:
Classify documentation articles in categories and provide subcategories if possible
Utilize the already existent categories and perhaps add one or two. The reasoning is that we already have many users that are familiar with it.
Think of the final user: new user to advanced user, not necessarily advanced developers
A working session during Contributors Days at WordCamp Vienna with about 15 contributors gave us some ideas. The results show the following recommendations:
Some articles need a more descriptive title
There are still articles that do not have updated information
Articles should be placed in one category/subcategory, even if the information could be related to other categories
There are unnecessary articles that must be removed. An example of this is the article WordPress Lessons that only offers links to other articles. Once the reclassification is done, there won’t be a need for this type of articles
Revisiting 170+ articles is going to take a lot of time. Some participants from WC Vienna agreed on continuing reading the articles but we will need more people
We are looking for volunteers that would like to help us with the classification and or would like to add a working session during contributor day at WordCamps.
@leogermani gave an update on the Handbook refresh effort and found out that the “Welcome box” is really outdated with confusing links, so he started a proposal to change that as well as give the Handbook a new home page with a short overview and links to more detailed pages
@leogermani also raised the issue about our internal codenames such as DevHub and HelpHub which can be confusing for end-users, so instead he decided in favor of using developer.wordpress.org and wordpress.org/support, respectively
@kenshino agreed we should stop using codenames in public information and address them by their URL only or both codename + url.
@milana_cap mentioned that we might still want to explain our codenames on specific detail pages in order to help users find the appropriate Components on the Meta Trac when they wanted to raise issues
WordPress.org vs. WordPress.com
@sukafia raised the WordPress.org vs. WordPress.com issue again (reminder: people confuse the two when looking for help, documentation)
@tomf added that they had the same issue during content migration where they noticed some content linking to WordPress.com docs when it shouldn’t have (we’re only concerned with WordPress.org here)
@kenshino asked whether we had a list of content that contains outdated or irrelevant WordPress.com links and @tomf answered that we didn’t. As such, @tomf agreed to lead the effort to audit content and compile a list
Open Floor
@leogermani was tasked with reaching out to #meta for statistics but didn’t receive anything back yet and doesn’t know who to specifically reach out to. @kenshino suggested to have a ticket open on Trac to help make it happen
@estelaris organized an interactive session at WCVienna this past weekend and together reviewed a series of articles and classified them with proper categories and subcategories
@estelaris mentioned that some articles didn’t have proper titles, other articles were (very) outdated and finally some articles were redundant in that they only linked to other pages
@estelaris agreed to @kenshino‘s invitation to write up some notes from the working session and post them on this site
@kenshino observed the efforts of @estelaris (Categorization) and @tomf (Content Audit) to be complementary and recommended they worked together
@kenshino mentioned that @coffee2code updated everyone with the appropriate Team and Contributor badges. Also, there’s a list of people that shouldn’t be holding a Team badge anymore due to inactivity
@valentinbora to post DevHub migration cross-check code to GitHub [update: done]
@milana_cap to update workflow for facilitating a meeting by including a step to review prior meeting notes
@milana_cap@kenshino to confirm usage of CrowdSignal or another service for hosting the survey
@atachibana to coordinate survey review before it goes live
@leogermani to review and update the Handbook and welcome box to attract new contributors
@leogermani to reach out to the #meta team to ask for stats to help highlight how important, popular and relevant docs are, as well as stats to support the survey (most viewed pages, devices used, referrals, searches etc.)
@valentinbora updated the team about a quick tool he’s written to cross-check migration status for Functions as he found quite a few pages out of sync in the Sheet vs. their actual live status. Before automated corrections there were 480/1069 Functions done (44.9%), after corrections we’ve won some and lost some, tallying to 374/1069 (35%)
@leogermani reminded everyone that the purpose of the survey is to learn: “How complete is our documentation and how can we improve our user docs?”
@themiked considered the survey to be asking some questions that could be inferred by statistics instead
@mkaz asked whether the survey was to be taken from a user’s or a developer’s standpoint. @leogermani clarified that it’s both
@themiked mentioned that the question “How complete is our documentation” is a difficult one to answer for end-users but we could still give it a try
@leogermani encouraged feedback for the survey to go to the p2 post linked above in order to have it all in one place but would like to hear from @bph in terms of the roadmap for the survey, with WordCamp Asia in mind.
Comments for the survey should be added by February 12th in order to prepare the survey well enough in advance before WordCamp Asia happening on February 21st, 2020.
@mkaz considers open ended questions to be difficult for end-users to answer and is wondering whether end-users get their answers from official documentation or elsewhere
@bph, @leogermani, @milana_cap discussed where to publish the survey, be it CrowdSignal or Pollbuddy vs. Google Forms. @kenshino should have something to say about that
@kenshino@milana_cap agreed to first focus on gathering the right questions to survey for before February 12th
@leogermani would like to attract more people to contribute to Docs and wants to review the Welcome box on the handbook page and bring documentation up to date to make it easier for newcomers.
@atachibana mentioned @estelaris‘ suggestion to reorganize the documentation tree with categories and subcategories.
@valentinbora suggested reviewing barriers to entry alongside motivational efforts for new contributors
@kenshino suggested to simplify the docs badge tracking Sheet to just two tabs. Any project leads can add contributors and they’ll be awarded a badge without question.
Open Floor
@valentinbora posted some tickets regarding DevHub and Explanation post types to help with Codex to DevHub migration (see more)
@leogermani@milana_cap mentioned @netweb was working on making it easier for setting up a local HelpHub environment for new code contributors to join in
@sukafia would like to know how to suggest edits to the HelpHub (user documentation) and @milana_cap suggested to ask in the #docs channel directly on Slack
@felipeloureirosantos posted an update regarding Brazilian Portuguese (pt_BR) docs. They have 5 new translated pages, 1 page in progress and a new contributor over the past week
@leogermani and @valentinbora conferred about the migration process, specifically that there’s little room for automation regarding redirection, but the redirect itself could be taken care of by an automated script once marked Ready for redirect
Now with DevHub and HelpHub migration in full swing, we are ready to survey WordPress users about the usefulness of our documentation.
In preparation, we’d like to collect topic suggestions from WordPress documentation team members and people who pay attention to the Make / WordPress blogs. Ideally, the questions can be reused yearly to gather information that will help inform our team’s work in the future.
The goal of this specific survey is to learn “How complete is our documentation and how can we improve our user docs?”
Example: Where were you able to find End User documentation on wordpress.org?
Yes, after searching and looking at a few pages.
Yes, right away via the Support pages
No, I couldn’t find them and gave up
No, I read about the Block editor on someone else’s blog
Didn’t know there was documentation
In this example, we want to learn how hard it is for those taking the survey to find the documentation for the block editor, the big change to how end users work with WordPress.
This survey, of course, is not just about the block editor, but all documentation.
Please add your comments by February 12th, and we will be able to prepare the survey in time for launch at WordCamp Asia, February 21st.
We also need volunteers for the team to create the survey. Please leave your name in the comments if you would be available to work on the survey between now and Feb 19th, 2020.
Facilitator: @kenshino Note taker: @milana_cap Next meeting facilitator: still don’t have one, feel free to apply.
Function reference redirect status
Thanks to @marcio-zebedeu and @stevenlinx, we have re-routed 447 (of 1069) pages, which is 41.8% in total. They re-routed 125 pages within just two weeks. Thank you so much!
Next week Facilitator: @kenshino (but invite for other meeting facilitator is open, please comment below if interested)
Team workflow and badges
@felipeelia: workflow docs are being constructed on Trello. @milana_cap is the one to ask for access if needed.
Badges are being discussed in this P2 post. The contributor badge has been discussed for a while now, trying to reach a number of X micro contributions. On his last comment there, @felipeelia suggested to give the badge right away, just as in Core and Meta. @bph added that there is precedent on other teams and make the contributor badge seen right away: it’s the best onboarding tool we have.
@kenshino shared some worries about relevancy: “if we say that fixing a typo is fine – we’ll have a rush of requests to do that to farm badges”. Indeed, Core and Meta have automated system to give props to people who contribute on Trac, based on commit messages. There is no such system for Docs.
@felipeelia argued that 1) People receive core/meta badges sending a 1-line patch ; 2) Coming in to Docs Slack team and reporting a small typo does require some effort. @bph added that working out how to communicate a fix to the Docs team is a significant step. even if the contribution is just a typo fix. @kenshino agreed, but the team must keep an eye on abuse to tighten those rules if needed.
Regarding Team Badges, @kenshino proposed to set up a sheet and to give edit access to people that are running projects within the Docs Team.
HelpHub Survey
Reminder from previous meeting discussions: The goal is to build the questions of the survey with the general theme being “How do you think we can improve the WordPress documentation?”. Some questions using the likert scale to track how good it is now so the Team can repeat the survey in the future. Some open fields to get proper feedback so it’s possible to define future projects better. That would be great for this survey to be ready for WordCamp Asia, in less than one month.
@atachibana is coordinating the effort. @bph proposed to assist on this task.
Step 1 is to start a Google Doc in the team’s shared folder.
This survey and the Docs team focus for WordCamp Asia are set to be the next meeting focus.
@bph proposed to draft a P2 post to ask for questions proposals. @kenshino proposed to review this draft.
