Request for Comment: Questions & Ideas for our Upcoming User Survey

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

  • 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.

Documentation Team Profile Badges

This discussion is happening for a very long time without a concrete result so far. So let’s try to define our system and add results to our Handbook. This should avoid all misunderstanding in the future, at least for a while.

Things to consider:

  • When does contributor get a “Documentation Contributor” badge? I think we should define this for every documentation team project.
  • When does contributor get a “Documentation Team” badge?
  • Are we going to remove “Documentation Team” badges due to long time inactivity etc? In this regard I think we agreed long time ago that “Documentation Contributor” badge will never be removed.
  • How often are we going to evaluate the state of badges? Every 6, 12 months?

I’d also like us to take a look at our team page as there are people who still don’t have even “Contributor” badge and are listed as a part of a team.

Everyone are welcome to participate in discussion. Please leave your thoughts in comments section.

Summary for Docs Team Meeting 20th January 2020

Facilitator & Attendance

Facilitator: @felipeelia

Attendance: @milana_cap, @atachibana, @marcio, @bph, @audrasjb, @tjnowell, @nullbyte, @pbrocks, @carike, @tomf, @kulsumsiddique, @nobnob, @kartikshukla, @estelaris, @kenshino, @clorith and @fierevere.

Note-taker: @audrasjb

Next week Facilitator: @kulsumsiddique

Meeting transcript on Slack

DevHub migration status

@atachibana shared some stats about this project: 322 of 1069 pages were re-routed from Codex to Code Reference, which is 30.1% of all.

This is one of the ongoing efforts of the Documentation team. If anybody wants to help, they can contact @atachibana via DM or via #docs Slack channel.

New contributors are encouraged to read this handbook page to learn more about contributing to HelpHub articles.

Discussion on the Docs team organization in general

As WordCamp Asia is coming, it would be nice to reach an agreement on two items: Team Workflows and Badges distribution.

Team workflow

It refers to reporting an issue about WordPress documentation. There is a Trello board for that. Most workflows are covered, if not all.

@milana_cap hopes to have the Workflows page published in the first week of February.


Contributors are encouraged to leave comments and suggestions on this post by the end of this week so @milana_cap can start working on a P2 proposal.

@felipeelia pointed out the example of someone who noted an error on one of the available docs and asked if they would be elligible to receive the docs contributor badge. @bph noted that it’s a micro-contribution. Several micro-contributions could lead people to receive a contributor badge. @felipeelia pointed out that it would need to keep track of each contribution in a document. @bph added that normally each contributor could keep track of it and let the Team know, when the threshold is reached.

@estalris noted that the design team do triages and people who participate on triages don’t receive a badge, because that is a micro-contribution. Only members with a specific project or role in the team are the ones that receive badges. Note: it’s for the Team badge.

Support team has a 400 replies goal to receive the contributor badge. Becoming a moderator comes with the team badge.


@atachibana is working on the progress and will prepare something for the next meeting.

@kenshino said he would love for that Survey to be ready to be distributed at WC Asia, in one month.

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.

@estelaris worked on the subcategory issue That was her first draft in trying to organize the articles, but she needs help to define the subcategories.

A discussion started about the relevancy of categorization, but the Team agreed categorization makes sense when there is a lot of content as users would be able to filter what they want to look for. @kenshino noted that we’re trying to solve a discovery issue and those won’t be solved with one method. Categorizing them is a start. But a proper search system is also necessary.

@estelaris and @atachibana are going to work together on sub-categorization system.

New readme.txt file for the Developer Handbook

@carike noted that the Core Privacy team discussed the proposed headers for readme.txt files. There is some debate about whether external calls need to be one item or split into three. Everyone agrees with the headers in general though. Next step is a meta ticket. They cannot update the readme.txt before the new headers are added, as this would lead to confusion.

Custom fields page

@leogermani edited the Custom Fields page as previously discussed. He added an entry to the Workflows card in Trello about Code reference.

#meetings, #summary

Trac/Trello Discussion – The way to report and discuss documentation issues

This discussion started in Slack during one of Docs team meetings. It was discussion about the best tool for tracking progress and issues for block editor end user documentation. However, the question of tool is widely applicable to all Docs projects, hence the need for this post and discussion.

Having complete documentation on Codex made contributing to Docs team easy in a way that everyone, as long as logged in, could modify existing or add completely new parts of it. However, this method had its flaws. It was impossible to track which parts of documentation were modified. And if we can’t track modifications then we can’t check the correctness of newly added information as well as the quality of code examples.

It took few years but we moved big parts of Codex to new places, built on WordPress. While we have more control as complete content goes under our review, this move made contributions to documentation team fairly difficult. The process itself is unclear, different Docs team’s projects use different tools (none of which covers all we need) but the common scenario we end up with is people reporting issues in Slack #docs channel.

The Tools

Documentation team uses several tools in contributing process. We have several Trello boards with more or less activity. Also, progress for almost all projects is tracked in Google Docs.

HelpHub content is tracked in Google Drive while development uses GitHub repository for development and Meta Trac for production issues.

Contributing to code reference can be done with code examples through User Contributed Notes (e.g. User Contributed Notes for activate_plugin() function) or with inline documentation via Core Trac (which is more Core than Docs team’s responsibility).

Plugin developer handbook gets updated when someone reports issue in Slack channel while Theme developer handbook used to use Trello board but we handed over leadership to Theme Review Team (even though Docs team is still helping when needed).

Common APIs handbook uses Google Spreadsheet.

Block editor uses Trello board and Google docs for end user documentation and GitHub for developer’s documentation.

We also have Documentation Trac available. It hasn’t been used for anything before.

What is the problem?

Different projects have different workflows and, therefore, different tools. However, we have several problems to solve:

  • Access – while we do welcome everyone to contribute to Docs team, we also need to be careful with giving access to handbooks hosted at If we want to make sure that only curated info gets into handbooks we need to limit access. That also means that whole burden of reviewing and maintaining handbooks falls on these few people who have access.
  • Keeping track of contributions and contributors – the easiest way to keep track of contributions/contributors is to use tools we have available at (Trac and Slack). On the other hand, Trac is not the most intuitive tool for wider range of WordPress users and Slack tends to burry information so the history is lost in tons of archives. Also, in some cases it is important that we have a history of a decision/discussion available at one, easy to access, place.
  • Project managing – each project is different but it is a project nevertheless. It is important that the tool we use for it have project managing features which will make contributing to the project easier (joyful is preferable).
  • Onboarding and taking over – Onboarding is huge problem of every open source project and it’s naive to think we can solve it with one tool. But also, it’s not just to tool we need to onboard people in, it’s the workflow as well. The tool we chose and the way we use it should be intuitive enough not to stand on our way to contribute and not to make project depended on a specific person. Most of this could be solved with a detailed documentation on the workflow itself.
  • There could be more, leave your thoughts in comments.

What are we deciding here?

We are not trying to decide on one tool over the other. We are trying to discuss all the tools we already use, how they solve our problems and how they help our workflow.

Most importantly, we want to figure out the way for reporting and discussing Docs issues. Preferably, we would come up with a unique way for all docs projects but given the differences between projects, it wouldn’t be considered as a failure if we don’t.

However, it is important that we come up with a way to report and discuss issues for each project. Results of this discussion will end up in our Handbook as a reference for contributing to Documentation team.

Please, leave your thoughts in comments.

Agenda for Docs Team Meeting 6th January 2020

Our next Documentation Team meeting is scheduled on

Monday, January 6, 2020, 15:00 UTC

in the #docs channel on Slack.

As we are back from holidays we won’t be focusing the meeting on any topic but rather cover all projects in where we are and what is next.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Discussion on the Docs team organization in general
    • Workflows
    • Badges
  4. Docs Team Handbook
    • Workflows and badges pages
  5. HelpHub
    • Progress of the survey
    • Feedback section – 4915
    • Mobile menu – Trello card
    • Localisation
  6. Common APIs Handbook
    • i18n pages
  7. DevHub
  8. New readme.txt file for the Developer Handbook
  9. Open Floor

Summary for Docs Team Meeting 16 December 2019


Facilitator and Attendance

Facilitator: @kulsumsiddique 
Note-taker: @udfibonacci

@aurooba will be facilitating next week’s meeting.

Attendees: @aurooba, @bph@atachibana, @milana_cap, @nao, @Carike@leogermani, @softservenet, @kenshino, @estelaris@nullbyte@pbrocks, @passoniate,

Trello / Trac workflows

@aurooba started a discuss this post( Trac/Trello Discussion – The way to report and discuss documentation issues ) and @milana_cap proposed to use Trello for document management.

@leogermani suggested that we should update our “Current projects” page to reflect more or less what you have posted on you p2 post, describing all the things we are working on and where are they organized. And we try with Trello for this project.

Everyone interested to help gives @milana_cap your trello usernames if you are not already in our team.

@bph opened a ticket #4915 to add comment or feedback section to End User Documentation page for low-friction interaction.

HelpHub Updates

@atachibana reported that no update for HelpHub and all of contents were migrated and new Release Notes such as 5.3.1 were added by core team appropriately.

Document Team will conduct a survey about HelpHub (Before Feb/2020?)

The mobile menu for the articles

@estelaris started a discuss that the categories and the number of elements ( ). For further discussion, refer the Trello card.

Common API Handbook

@leogermani has edited the Themes handbook I18n page and linked it to the new page on Commons APIs. The plugins handbook on i18n still need some efforts.

DevHub Updates

@atachibana reported: For Codex redirection to DevHub, there were some progress but again worksheet data were deleted by someone. I’ll restore them and am thinking to set the lock.

HelpHub Localisation

No time to discuss.

Next week meeting focus

The next meeting is on Jan 6.

Agenda for Docs Team Meeting 25 November 2019

Our next Documentation Team meeting is scheduled on

Monday, November 25, 2019, 15:00 UTC

in the #docs channel on Slack.

Focus: Docs Team Handbook

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Docs Team Handbook Discussion (40 mins)
    • Adding a section on facilitating meetings
    • Areas of improvement + assignments
  4. Project Updates (20 mins)
    • Common APIs Handbook
    • HelpHub (& localisations)
    • DevHub
    • Docs Team Handbook
  5. Open Floor

Feel free to comment if you have items to add to the agenda.

Agenda for Docs Team Meeting 11 November 2019

Our next Documentation Team meeting is scheduled on

Monday, November 11, 2019, 15:00 UTC

in the #docs channel on Slack. Today we will have feedback from Contributor Day in WCUS and WCTokyo. Unfortunately, @milana_cap who lead WCUS won’t attend the meeting. So any feedback from team members are welcome.

Also, we want to discuss about rename of Common APIs handbook so that it can cover common development topis such as I18N or license.

Items to discuss:

  1. Attendance
  2. Note taker
  3. Select facilitator for next Docs meeting -> Jon will run
  4. WCUS Docs Team Feedback
  5. WCTokyo Docs Team Feedback – @atachibana and @nao
  6. Content Migration from Codex to HelpHub & DevHub – @atachibana
  7. HelpHub localization
  8. Common APIs Handbook – @atachibana and @leogermani

Open Floor

Feel free to comment if you have items to add to the agenda.

l10n and i18n on Common APIs Handbook

This post is a starting point to discuss how we can organize the documentation around Internationalization and Localization on the new Common APIs Handbook.

Common APIs Handbook is the new home for documentation on APIs used across WordPress that is not specific to themes, plugins or any other component. There you will find docs on Options API, Shortcode API, etc. (Note that content is still being migrated so there might be incomplete pages).

This should also be the home for the i18n and l10n documentation. So let’s see how this could look:

Current documentation

Here is a list of the current documentation on this topic we have (and that I could found)

And then you have, at the top of that page, a link to documentation on both new Themes and Plugins Handbooks.

You will notice that we have duplicated content on these pages. “How to internationalize…” pages are very similar, with small differences in how to initialize text domains and where to save the files. “Localization” pages are pretty much the same.

Finally, we have the documentation on the new Javascript support for i18n introduced last year. This didn’t make it to the Docs yet:

What we could do

Here is my suggestion on how to organize this:

  1. Create an “Internationalization API” page on the Commons APIs Handbook with content from the current Codex page and the “How to Internationalize your theme/plugin” pages.
    1. These pages already have the same content
    2. Make sure to make it generic, in a way it works for themes, plugins, and the core
  2. Redirect Codex page to this newly created page
  3. Edit “How to Internationalize your theme/plugin” pages, leaving only plugins/themes specific information, and then linking to the “Internationalization API” page for general guidelines
  4. Add to the “Internationalization API” page the section about i18n support in javascript. If we have permission, Pascal’s post could be incorporated.
  5. Finally, we have to find a home for the “Localization” page. This is not properly an API, so maybe it could be an article on and all i18n pages could link to it

Changing the nature of our weekly meetings

So HelpHub has already been deployed and other projects are in need of some focus.

I’ve been thinking about how to make our meetings more useful. Meetings that are just about updates aren’t the best use of everyone’s volunteer time.

Meetings that require involvement but no one is prepared for ain’t the best either.

So I’m hoping that we can improve how we run the meetings. I’d love for everyone to suggest something.

I’ll start off –

  1. Let’s rotate facilitators and note takers. Both roles have the ability to help someone really get into the groove and understand the Docs Team.
  2. Let’s change all meetings to Docs Team meeting (no special HelpHub dedicated only meetings)
  3. Let’s time-box each section of the meeting
  4. Let’s have focuses for each meeting. (e.g.)
    • Docs Team Meeting (60% time on HelpHub discussions, 40% other pieces)
    • Docs Team Meeting (60% time Docs Handbook, 40% other pieces)
    • Docs Team Meeting (60% DevHub discussions, 40% other pieces)
    • Docs Team Meeting (60% Flagship WordCamp contributor day discussions, 40% other pieces)
    • You get the drift!

Any better ideas? I’d love to hear them!