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
Last year it was proposed to replace auto generated excerpts with ToC list items. On today’s meeting discussion it’s been decided to use manually created excerpts which would contain the point of the article in one sentence. Short and concise. more meaning, less space.
This was unsolved for a long time. We decided it’s important to order posts according to its content complexity so it resembles “Step 1, Step 2..” format or, if this doesn’t apply, to order according to post’s “importance”. As this is difficult to apply automatically to all categories we decided to use Post Attributes order and intentionally create order which we will specify in WP_Query.
As some articles have more than one category assigned, in which it might have different “importance” and order, we decided to make larger steps between posts using the same logic as menu items in dashboard. So two posts in a succession would have 10 places in between, rather than 1. This should also help with ordering articles published in the future.
Viewing single article on smaller devices reveals the sidebar throughout the whole visible area. The rest of Handbooks solve this by hiding the sidebar altogether. @milana_cap suggested to place search form and single posts navigation instead of sidebar. For this single posts navigation to be useful, the order of posts (above) should be logical and intuitive.
@estelaris said that she’s working on templates and will discuss this issue on #design team meeting this Wednesday, as this is effecting all WordPress.org Handbooks.
@estelaris is working on overview of HelpHub design. Her analysis can be found in Google Spreadsheet: https://docs.google.com/spreadsheets/d/1ZnhtiLxqjXviFlnWsDE5L8YRiBXtkmanvM8doIc1lrg/edit?usp=sharing
After we agree on design template we need to have #accessibility review and usability test. @samikeijonen kindly accepted to perform these testings once we have everything ready.
Mobile view of HelpHub is identified as making HelpHub hard to use so we are going to prioritize those fixes if we don’t get the git + svn work done by this week.
Content
There are no requests for new pieces that we need to write. @atachibana volunteered to follow the state of Block Editor user’s docs as it is still hard to be found by people. @bph volunteered to help. They will reach out to @karmatosed regarding improvements.
We would like to have some input from Support Team on obvious gaps for Block Editor Docs. @clorith will bring this up on their next meeting.
@leogermani did half of remaining redirects and updated the spreadheet, expecting to finish everything by the end of the week. @audrasjb volunteered to help, @juliobox is already on it.
Design
Skipped due to missing reps.
Rosetta Releases
Japaneese release gathered 11 volunteers. Serbian rosetta still doesn’t have HelpHub enabled. @kenshino will ping @sergey about this.
Open Floor
We currently have 288 user notes (DevHub comments) in queue. @audrasjb volunteered to help with reviews. @softservenet will start a spreadsheet of Docs Team’s ongoing tasks and members working on them.
We’re currently trying to move issues form GitHub to Meta Trac to give proper visibility over bugs that affect the code base that was merged into WordPress.org
The team is working on checking if the issues are reproducible on WordPress.org and will migrate related issues.
@milana_cap has updated the list of developers that contributed code to HelpHub. We’re working out which badge to give (Meta or Doc) and will finalise this soon
It’s been raised that the forum and HelpHub landing pages are too similar. A discussion will be needed with @iviolini and @clorith to work this through
Gutenberg Handbook
@nosolosw mentioned that the Gutenberg docs have improved quite a bit thanks to the efforts of many people, and the main issue now is discoverability
It was recommended by both @Kenshino and @chrisvanpatten to get the contents of the current Gutenberg developer documentation into a DevHub handbook as a main focus and work out both the technical roadmap and the content re-ordering at a later stage.
@nosolosw will be conferring with the Gutenberg team over the next few days.
Google Season of Docs
In short – there’s 3 months that a technical writer (or more) that can sign up to write docs for WordPress.org
We could decide where the focus should be. It could be working on improving Gutenberg Docs or making sure we look at the other handbooks to review the level of technical writing that we’re at
@chanthaboune is looking into how we’d apply as WordPress.org and mentors are needed for this effort. If you’re interested, take a look at https://developers.google.com/season-of-docs/docs/mentor-guide and let us know you’re interested either via DM on Slack, a message in #docs or a comment on this P2 post!
Documentation Team Badges
After a bit of discussion, we’ve landed at a criteria
Documentation Contributor: You have contributed over X number of changes across HelpHub or DevHub.
Documentation Team: You regularly attend Documentation Team meetings and you are either a project lead or a team lead of a project.
Contributor badges are likely to be permanent and Team badges denote current activity over a period of 2 months.
We’ll likely have to work on the criteria a little more and will make a separate P2 post to solicit feedback before confirming it.
Maintenance of Theme Developer Handbook
The Docs Team would like to bring in the Theme Review Team to take ownership of the Theme Review Handbook (just as Plugins has done so for the plugins handbook).
@kafleg has been requested to form a team and work with @atachibana to bring the theme handbook up to speed.
You can read a transcript of the meeting via https://wordpress.slack.com/archives/C02RP4WU5/p1554130866012100
Now we have “Block Editor” icon on the DevHub main page: https://developer.wordpress.org/ But, the plan of moving contents is not clear from previous discussion. Can anyone explain it in the meeting or on #docs?
Open Floor
Feel free to comment if you have items to add to the agenda.
Version Text 77 of 349 completed (22%) mainly by subrataemfluence, 107 in progress (31%)
If anyone has interests in these activities, please read this document or contact @atachibana https://make.wordpress.org/docs/handbook/helphub/migrating-articles/
Development for Phase 1.5
@milana_cap submitted the updates First, all the issues are labelled as, Phase 1.5: https://github.com/Kenshino/HelpHub/issues?q=is%3Aissue+is%3Aopen+label%3A%22Phase+1.5%22 or Phase 2: https://github.com/Kenshino/HelpHub/issues?q=is%3Aissue+is%3Aopen+label%3A%22Phase+2%22
She is thinking of moving Phase 1.5 issues directly to Meta Trac. @milana_cap will work on immediate fixes for the blockers now and will coordinate with @netweb to work out next steps.
Design
@iviolini has taken over from @mapk as Design Lead for HelpHub.
There are issues labeled with Design tags on GitHub that will require @iviolini to review.
Content Migration check-in
@atachibana explain the updates about this. There are 3 or 4 active members. For Phase 1.5 completion, the numbers might be enough.
@milana_cap Will be at WC Nordic CD, they’ll have docs team and she will try to gather more volunteers for the Docs team. @kenshino will be on WC Bangkok and will work to get more volunteers.
Voice & Tone guide
@kadair updated it after all the comments received in https://make.wordpress.org/docs/2019/01/16/call-for-feedback-on-tone-and-voice-guide/ @kenshino will make a blog post and say that we’ve gotten a consensus on this and we’re publishing it as the official WordPress tone and voice guide – it’s still open to improvements of course (as with anything in WordPress)
HelpHub localisation plan
@nao and @kenshino worked on it. https://docs.google.com/document/d/1d5a64LN564zB-HrxvRr9u1zKepD5yaVYb-cL02r5euQ/edit?ts=5c47e862 @moghillfifi will give it a proper read through before we go on publishing. We will probably publish it on mid week.
You can join #docs channel on Slack for the more updates.
You can check out Slack for meeting logs – https://wordpress.slack.com/archives/C02RP4WU5/p1549897229001500
With the release of WordPress 5.0 and the new Gutenberg block editor, there are many changes in WordPress for users and developers alike.
For developers in particular, the changes are dramatic. As such, we also have a lot of new documentation to create: and we need your help!
If you’re a developer and have spent time working with Gutenberg, this is your time to shine. We’re looking for contributions in a few specific areas.
Examples
Most of the requests we get are “how do I do X?”, so we are looking for code examples and “micro-tutorials” that can help developers solve these questions and integrate with Gutenberg.
Contributions here are ideally in the form of a single markdown file, with at least a few hundred words that describe the problem and walk users through the solution, with complete code examples. They should link out to the relevant API documentation (where it exists) or to other areas of the handbook that offer further context.
A few ideas for contributions include…
How to register a sidebar plugin
How you might use InnerBlocks
How you could port a custom metabox to a custom sidebar plugin
How to trigger a modal
How to write block attributes to post_meta
How to use the color HOCs and components in your blocks
How to filter specific areas of the editor (especially panels in the document settings sidebar)
How to filter the available blocks in the editor
How to use the data module to retrieve post data within a custom component
Package documentation
Gutenberg is built with a collection of npm packages. Some of these packages have great documentation in their READMEs, but others don’t. This is another great way to contribute: choose a package, and improve the README in a pull request on the GitHub repo.
Each README should include:
Installation instructions (most have this already!)
General/basic usage instructions
Function documentation, if applicable
Links to other documentation that might be relevant/helpful
Component documentation
The new editor also leverages Components to build the user interface. These are provided inside the @wordpress/components package. Each component should have its own README that contains:
Basic usage example
“Dos and Don’ts” of how to use the component correctly (from a UX perspective)
Although these are our highest priority items, they are by no means the only ways you can contribute. The “Documentation” label on GitHub offers many more ideas. Picking a ticket and writing the documentation to solve the issue is a great way to contribute.
We’re all committed to making Gutenberg documentation the best on the web. Thanks so much for your interest, and we hope you’ll also consider joining our weekly meeting in #docs in Slack at 18:00 UTC!
Thanks to everyone who joined us for the kick-off Gutenberg docs meeting!
Below is a summary of last week’s meeting.
Opened with introductions and hellos, and a description of @chrisvanpatten‘s goals for the group
Set future meetings for 1pm ET/17:00 UTC on Tuesdays, in #docs on Slack
Discussion of where documentation would “live”
Goal is to continue allowing docs to be prepared in GitHub
@drewapicture raised some questions about what the Gutenberg handbook represents, suggesting it not exist as a mono-doc when merged into core
@kenshino raised the idea of splitting into separate handbooks: auto-parsed documentation in DevHub, developer handbook in DevHub, and user handbook in HelpHub
(@chrisvanpatten also added a contributor handbook to be considered too, likely to live on GitHub for now)
Established next steps:
Lock down high level documentation outline
Open a PR to reorganise the documentation
Determine list of holes in documentation
Begin assigning writing tasks in GitHub issues/high level project/milestone
Established next meeting for Tuesday, 30 October at 1pm ET/17:00 UTC in #docs
</meeting>
I’ll post an agenda for our next meeting tomorrow a few hours before the meeting. Thank you everyone who joined us!
