Documentation Team Handbook Structure Proposal

For a long time our Handbook was almost completely useless for new contributors. It’s half empty and yet full of outdated information. We want to fix this. It won’t be easy and it needs much more than just a content update. It needs complete refactoring. And we need to change our perspective and treat it as one of our ongoing projects.

Refactoring progress is tracked in Trello board. This board is public and you are welcome to join, leave your comments or just follow the progress. Please note that this board is for refactoring purposes. Once we are done with it, it will be back to only team visible and used for documentation team’s work on Handbook. Contributions to the Handbook will be done through docs trac. Or at least we’ll try to use it.

In Trello board you can find proposed new structure and proposed changes for each page. Please take a look, think about its usability and how intuitive it is from the new contributor’s perspective and let’s discuss it on one of coming up docs meetings.

Proposed structure:

This marks following pages for removal:

Empty pages:

Unclear pages:

Outdated pages:

Merged to other pages:

Summary for HelpHub meeting 6 August 2018


@atachibana @kafleg @mapk @polkadotcreation @jesseowens @audrasjb @jeroenrotty @chetan200891 @kenshino @tomf @tomjn @joyously @felipeelia @kartikshukla attended

Phase 1 Updates

Still no concrete updates from Phase 1. @kenshino will be pinging the meta team and likely joining the meta team meeting to push this forward.

Phase 2 Updates

@audrasjb migrated the remaining pages onto HelpHub staging and has been working on template enhancements

We’ve created an issue to track linking WordPress versions from DevHub –

@audrasjb and @atachibana are working on improving the content format of the WordPress Version pages so that users and developers can get information relevant to them immediately.

@tomjn is working on Gutenberg functionality for HelpHub

@tomf is going through Contributor feedback functionality

You can view the meeting history in detail at

Docs Sprint Results and Roadmap

We've spent three days in Cincinnati and it's been hugely productive to get together and talk about the issues. We've also got some work done on the Theme Developer Handbook and the Codex.

Thanks to Kim Parsell, Drew Jaynes, Maria Scarpello, Eric Amundson, Ryan Ray, Ryan Markel, Hanni Ross, Jerry Bates, and Michael Krapf for attending. It's been fantastic to get docs folks together to talk, work, and hang out in person. Also thanks to Automattic, WooThemes, and 10up for supporting the event.

What follows are the results of the discussions that we had, along with a Documentation roadmap for the next two years.

From the Discussions

Issues that we face

We spent a lot of time discussing the issues that we currently face. This was backed up by the responses to the Codex survey, which we analysed at length. Some of the issues we have are:

  • Function Reference lacking examples, or examples are out of date
  • duplicate content
  • out-of-date content
  • Too many pages that deal with the same issue (we have 4 getting started pages!)
  • conflation of user and developer content
  • the lack of responses from WordPress users demonstrates that we aren’t meeting their needs and they’re going elsewhere for their content.
  • content is hard to navigate
  • content is way way way way way too verbose
  • too much irrelevant content

Documentation we need


  • support hub (like Mozilla &
  • “get started with your blog”
  • “get started with your website”
  • task-based documentation
  • glossary?


  • developer resources hub (like and Stripe)
  • code reference
  • plugin handbook
  • theme handbook
  • introduction to WordPress development (how WP works, the loop, etc)
  • knowledgebase
  • glossary

All of this content should be optimized for search.

What tools do we need?

  • multilingual support
  • editing/approval flow
  • method for surfacing revisions
  • attribution and credits
  • code reference beta
  • issue tracking system

Things we can do for quick impact

  • noindex forum posts over a certain age
  • reduce the content on the Codex pages that get a lot of traffic

Project Management Model

Upon reflection, it makes sense for the documentation team to work on one focused project at a time. We discussed adopting a model similar to the development release cycle. We will work on a project together for a period of time. Each project will have a lead (or two leads, as necessary), which will become the primary focus of the whole team for its duration.

These cycles will be independent of the scheduling for core development cycles.

What versions of WordPress do we support?

The Codex has a lot of content that refers to different WordPress versions. For example, the Post Formats page uses phrasing like “Since WordPress 3.1….”. This makes sense for API docs, but not for user docs. Our user docs should be written only for the latest version of WordPress.


The biggest challenge that we face is dealing with 10 years’ worth of content – this also means we are dealing with 10 years’ worth of incoming links. We can’t just delete pages; they have to be redirected. With every page (particularly those with large amounts of traffic), we’ll have to decide where to redirect them. This will be particularly difficult on pages that contain developer and user information – where do we direct the page to? The user docs or the developer docs?

Analytics & Optimization

To make decisions about where to direct pages and what documentation will have the highest impact, it will be useful to do some analytics on the Codex. Redirecting the pages will be easier if we know the types of articles that are linking to the Codex.

We should also do some research into the information people are finding via Google. For example, we can do searches for issues like “WordPress white screen of death” to see what results people are getting. Where are they getting their help? What are the top results on Google?

Once we have created different documentation types we should carry out user tests to make sure they are effective.

Credits and Attribution

To engage and retain new contributors we need a proper attribution and recognition model. Currently there are no “recent rockstars,” “core contributors,” etc. for support or docs. This was a major issue for people who responded to the Codex survey. Acknowledging contributions will raise awareness that this is a way to get involved with WordPress and encourage new people to get involved.

Learning Blogs

Currently, the Codex is used as a dumping ground for every type of content relating to WordPress that doesn’t fit on the blog. For example, we created a page on troubleshooting Javascript for the last WP release. In the absence of MediaWiki, we’ll need a place for these types of things. The support and developer resources could each have blogs that contain time-related resources, such as dev docs related to recent releases, or user docs relating to recent releases/events (e.g. how to migrate from Posterous, how to use the new media uploader, etc).

Help Tabs

We discussed the inline Help Tabs in the WordPress Admin. While we agreed that they’re currently not much help, any improvements to these would need to happen in connection with the core development team to make sure that the UI, UX, and content are best suiting users’ needs. If the core team decides that they want to make improvements to the help tabs, we’d love to work on that with them.


July–Dec 2013

  • Project: Code Reference
  • Simultaneous work on tools for the next cycle
  • multilingual plugin
  • editing flow
  • revision surfacing
  • attribution and credit
  • handbook virtual sprints

Jan–Apr 2014

  • Project: Developer resources landing page and site – follows directly from the code reference

May–Dec 2014

  • Project: Support Hub
  • landing page
  • Getting Started guides for websites and blogs
  • Task-based and search optimized guides
  • investigation into whether we need a knowledgebase for reference

Jan–Mar 2015

  • Dismantling the Codex (i.e., MediaWiki)
  • Moving and removing any remaining documentation
  • Setting up final redirects
  • Any further hub pages that need to be written

End Goals

The ongoing goal of the project is to reduce the amount of documentation for WordPress by reducing its scope to constrain it to the core project. This will be done by both eliminating unnecessary chunks of documentation and making successor documentation more concise. Separating user documentation from developer documentation will reduce confusion and aid in identifying documentation that can be pruned.

At the end of the two years outlined here, the goal is to retire the MediaWiki version of the Codex and have a fully-developed, effective, and usable WordPress-based documentation source.

Gallery of team scribbles

Theme Handbook Update Jan 24th

Friends, Romans, Theme developers, lend me your hooks…and let us together take “action”.
For those that haven’t heard, I am the editor of the Theme Handbook. I am responsible for  bringing together the different theme topics, to be written by volunteers like you, into a cohesive reference on building a WordPress theme.
With the help of Siobhan, Chip, and many others we have compiled the table of contents for the Theme Handbook.  The Handbook contains five different sections that are split among many different topics:
  • Introduction – Content Management in WordPress, What is a Theme?
  • Theme Basics – Template Files, The Loop, Template Tags, Theme Functions, Including CSS, Including JavaScript
  • Theme Functionality – Comments, Sidebars, Navigation Menus, Thumbnails, Image Galleries, Accessibility, Translation, Misc.
  • Advanced Theme Topics – Best Practices, UI/UX, Theme Customizer, Theme Options, Security, Child Themes
  • Theme Release – Required Files, Testing, Writing Documentation, Submission Process

Our team is in need of a few more contributors.  Each topic will be written by one or more volunteer contributors.   If you know of anyone that would be interested or perhaps a good fit for an open section please do let me know.

The next steps are to get the current volunteers access to the Theme Handbook site, find volunteers for the unclaimed sections, and get this show on the road.
The next IRC Docs Chat is today at 2100 UTC on #wordpress-sfd.  Hope to see you there.


Agenda for Helphub Meeting July 11


So we’re back after WordCamp Europe 2017 and WordPress Summit 2017! Lots of things to do!

Time/date: Tuesday, June 11, 2017, 15:00 UTC in #docs

  1. Attendance
  2. Migration Updates
  3. Design Updates
  4. Development Updates
  5. Community Summit
  6. AOB

Pinging @atachibana @jon_bossenger @karys @nlarnold1 @greensteph @sarassassin @bethannon1 @juhise @hlashbrooke @sergeybiryukov @bravokeyl @quitevisible @ankitguptaindia @anevins @justingreerbbi @carl-alberto @geoffreyshilling @normalize @hardeepasrani @danhgilmore @wizzard_ @cristiano.zanca @tacoverdo @lumberhack @krogsgard @clorith @versatility @mapk

If I have missed any usernames, it’s not on purpose and do consider yourself invited to the meeting.

WordPress Admin Help

Here’s a draft of the proposed project scope:

As part of the move towards developing features in plugins, we’re looking at making improvements to the WordPress admin help. On Monday at 3:30 UTC we discussed the issue in #wordpress-dev

The Problem: The current Admin Help is hard to find unless you know it’s there. The content lacks any focus; it’s simply a description of what’s on a particular screen and doesn’t add any particular value. It’s possible that we’re failing WordPress users by a) not providing useful help in the Admin, and b) not providing adequate basic resources in the Codex.

Work was carried out by @chexee in ticket 21583 on making Help and Screen options more discoverable.

In the State of the Word, Matt talked about the 96% attrition rate on, and how it was probably higher on WordPress due to the extra steps. If users are getting frustrated and walking away from WP, how can we prevent that frustration?

Goal: to alleviate frustration in people who find the admin too difficult to use.

(Note: changing the Admin is outside of the scope of this project. We are creating help for the admin as it is. However, testing and research will inevitably show up issues which we should record and make available for others to work on should they wish to).

Some questions to keep in mind:

  • how can we best provide admin help to users?
  • what help do users need?
  • how can we ensure that help is unobtrusive for people who don’t need it?
  • what tools are available to us?
  • should we de-couple screen options and help?
  • how can we ensure that the help is accessible to all WordPress users?

The process:

1. Research & Identifying the Problem
Before fixing the problem, we need to discover what problem users are facing. @trishasalas has started writing some questions for user testing so we can identify at what stage the pain points are appearing. For example, are they baffled when they first log in to WordPress, or are they having problems when they are in the middle of work?

@jazz3quence has started researching how other platforms are implementing admin help, and the tools available. Once we have identified the problem we can match a tool to it.

We should also draw up a list of WordPress plugins that are providing admin help (WP-Help, for example).

2. Mockups
Mockups and sketches will be created for the following:

  • the user interface
  • the user’s journey and interaction with the functionality

3. Design & Development
A UI designer will put together the interface (to match MP6) and developers will be needed to create the plugin. After the first version we go on to the next phase.

4. Test and iterate
Testing and iterating for fun and profit.

5. Finish!
Time for tea, beer, or scotch.

Who’s needed:

It would be desirable to get the following skills involved:

  • developers
  • UI designers
  • technical writers
  • WordPress users (for testing)
  • people who run WordPress training (to provide feedback)

#3-8, #admin-help

WordPress 3.8 Dashboard Help

We had a chat in #wordpress-dev this morning (afternoon for some folks) about WordPress dashboard help (i.e. the component currently known as the help tab). Hopefully @siobhan will post back here with some notes because I’m not good with notes 😉 but I’m gathering some screenshots of help systems as I meander through my day here:

Feel free to share any you find and I’ll add them to that Google Drive folder. My only real criteria is “what happens when I click help here” and then take a screenshot of whatever comes up.

#3-8, #admin-help

User Testing for WordPress 3.8 Admin Help

Following up on the chat from Monday at 15:30 UTC about inline help or now more appropriately called Admin Help (see irc logs) . I’ve started some very rough outlines for user testing scripts. I’ve gotten 2 scenarios with slight variations in each. They are just outlines at this point and need to be fleshed out a bit, you can view them here ->

Feel free to comment, add, subtract, etc…this is the first formal user testing I have done so I’m learning as I go here 🙂 Kinda fun and very eye-opening.

#3-8, #admin-help, #inline-help

Admin Help – User Personas

Note: This is taken from a past Happiness Engineer meetup project focused on users, so there may need to be some editing here to better fit our understanding of users

Persona 1

Marci, 55
Married with children, one grandchild. Empty-nester. All her help for set-up comes from the web.
Husband, George, is the local pastor, and she has started a blog for his church, wanting to proactively be modern and support him. She is unwittingly about 5 years behind technological trends.
Enthusiastic, a bit flighty.
Located in the American Midwest – Ohio
AOL user


  • Upload videos or shortcode from the YouTube
  • Find the right theme
  • Add users/subscribers
  • Add posts
  • Create a custom menu

Tech-savviness rating: 1/10 (1 is least tech-savvy, 10 is most)

I’ve read the page for custom menus three times and been following it, and I can’t see my pages

Persona 2

Angelo, 40
Small business owner
He’s pretty successful locally
Someone told him about .Org, and he struggled with it, but learned about plugins and themes.
He doesn’t want to spend a lot of time on this – it has to just work. He will be stingy with his money depending on how much perceived value something has.
He has a teenaged son.
Married to his high school sweetheart
Hotmail user.


  • Theme
  • Upload a logo
  • Much more a static site, but will eventually branch into some light blogging.
  • Wants to have increasing traffic over time to increase business

Tech-savviness rating: 4/10 (1 is least tech-savvy, 10 is most)

“I’ve spent 5 hours of my time on this. I don’t have time, I need this done.”

Persona 3

Jessica, 20s
Personal blogger
A few years out of college.
Relatively savvy – grew up with technology. Has an iPhone.
Knows a little HTML, but not that into it.
Has been blogging on Tumblr for a few years, but now wants to be able to have more themes and a bit more control behind the scenes.
Stays on top of trends.
Gmail user.


  • Themes
  • Flexibility to change domains when hobby changes
  • Wants to curate followers/increase followers
  • Publicize on social media

Tech-savviness rating: 7/10 (1 is least tech-savvy, 10 is most)

“How do I pick the image that gets posted to Facebook”

Persona 4

David, 35

Does web design work professionally, but not on WordPress
Lost a bet on a basketball game, and now has to set up a site for a friend.
Very savvy, knows a lot about computers.
Thought that setting up the site on WordPress would be a 10 minute job, and now it’s been a few hours and he’s frustrated.
Comes in with very specific expectations that may not actually be accurate on how things should work.
Hosts his own email address through Gmail on his host.


  • Themes
  • Set up site structure (pages, maybe a blog)
  • Set up a home page
  • Where does the HTML go?

Tech-savviness rating: 9/10 (1 is least tech-savvy, 10 is most)

“I work with websites a lot, and I’m setting up a site for my friend and I can’t figure out this WordPress thing. How is this easy exactly?!?”


Summary for Documentation Team Meeting February 16



@drewapicture @Kenshino @desrosj @hardeeparsani @cais @milana_cap @kafleg @mrahmadawais @juhise

Change of timing

We moved the meeting forward this time due to conflicting schedules. Apologies to those who were thinking attending it at the original timing.

We are perhaps thinking of moving it up 2 hours to 2017 15:00 UTC. What do you think?

General Updates

  • Helphub is moving ahead slowly.
  • Theme Developer Handbook was released
  • DevHub comments / code suggestions clearing is going too slow (@drewapicture will help to clear)

WordPress Community Summit 2017

The community summit will be held in conjunction with WCEU this year in Paris. The last time it was held alongside WCUS in Philadelphia in 2015.

The summit will be held June 13-14, preceding WCEU, June 15-17.

The Community Summit is less like an actual contributor day and more of an opportunity to discuss and make decisions and plans for your respective teams.

Typically, for instance, you’ll see the core team make roadmap-related decisions about what’s coming up in core development for the next two years. Talk about priorities, active projects, projects you want to work on, Very much like a retreat.

The Docs team launched the Plugin Developer Handbook, for instance during the San Franciso Summit in 2014

It usually proves to be very productive for every team that meets and has a presence. It’s also an opportunity to have discussions with other teams, especially for discussing cross-team projects like helphub (docs + support + meta), devhub (docs + meta), inline docs (docs + core), etc.

People attending

@kenshino, @drewapicture

People wanting to attend

@milana_cap, @atachibana

We would love to have more people to attend from the Helphub, Theme Developer and Plugin Developer Handbooks teams. If you are working on a documentation project for, or if you’re a documentation junky who wants to contribute, please let @Kenshino or @drewapicture know that you’re interested.

Attendance to the WordPress Community Summit is through nomination by the Make / WordPress team leads. We can only nominate you if you let us know you’re interested!

We will have to submit this by the end of February. Please let us know by then!

Summit Discussion Topics 

  • Game plan for recruitment
  • Onboarding Plan
    • We get a ton of people wanting to contribute but we have no established recourse for providing that access.
  • State of Doc’s Team (own) documentation
  • DevHub and Helphub translation Mechanism (Docs + Meta + Polyglots)

We would love to cover more in the summit, so please post topic suggestions in the comments!

WP CLI Code/Command Reference

We’ll probably be restarting devhub meetings soon, so for now, I’d say just leave the command docs in control of and we’ll look at short-term and long-term solutions to bringing those docs over.

The upside of wp-cli command docs is that they’re already written in PHP and use phpdoc to parse into the staticly-generated pages, so we might be able to fork the parser we use for the code reference.

Read the meeting transcript in the Slack archives. (A Slack account is required)