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 wp.com, 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: https://drive.google.com/folderview?id=0B3-2b7pMjiwXeEhpbzBNelFlUGc&usp=sharing

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 -> https://docs.google.com/document/d/14UPN3u32QqOt0b9l0XLe9MbDKyhRdYJcLegOBIV8DCs/edit?usp=sharing

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

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 WordPress.org, 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 wp-cli.org 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)


Theme Developer Handbook released

After around close to 2 years of development, through a total of 3 different teams, we have released the Theme Developer handbook, thereby completing the Developer Hub’s goal of having proper developer docs for the main aspects of WordPress.

This could not have happened without a few of the initial leads and project pushers – @siobhan, @samuelsidler @sewmyheadon @lizkaraffa @thoronas @jcastaneda @grapplerulrich @anthonynotes @topher1kenobe.

The list of people involved (not yet complete) is documented here and last count puts us at close to 100 people involved in the handbook in one way or another.

The handbook has been released in it’s version 1 form and is updated all the way to 4.7.

There’s always more to do and the team continues to manage and improve the handbook on Trello.

Please do give us feedback using the methods detailed here.

We hope this helps everyone make better themes!

Get cracking at https://developer.wordpress.org/themes/

Props to the editors who came in after the handbook progress stalled for awhile @kenyasullivan @xfrontend @burlesonbrad @nao @jacobmc @hardeepasrani @sheebaabraham @boogawooga @rahulsprajapati @viniciuslourenco @kafleg @atachibana @sarahovenall @sushil-adhikari @celloexpressions @juhise


Agenda for Helphub meeting December 13


We have missed a few meetings due to holidays and WCUS. Let’s get one or two in before Christmas and the New Year hits us again!

Time/date: Tuesday, December 13, 2016, 14:00 UTC in #docs

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

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

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


Volunteers needed for Theme Developer Handbook

Hello fellow Doc-lovers,

As you may know, DevHub has already been up for awhile and large strides have been made by @drew to get all portions of DevHub up and running.

Recently, I took over the management of the Theme Handbook project and I believe we’re about 80% done. (was 90% but we’ve had a few major releases since then)

Thanks to @lizkaraffa & @thoronas for leading the team thus far!

There are a 2 major areas (blockers) that will need to be finished before we can do an initial release of THB.

  1. Clearing the To-Do list located at https://trello.com/b/sBXllyQT/theme-developer-handbook
  2. Updating specific articles to reflect recent core changes such as adding ‘Custom Logos’ under core supported features

The beta form is currently at https://developer.wordpress.org/themes/getting-started/

We need you, doc lovers & previous contributors to the Theme Handbook to help us get this to the ‘release-able’ stage.

We are currently managing the project on our Trello Board

If you’re interested to help, please ping me @Kenshino on #docs, Slack or simply comment here!


Docs-focused Bug Scrub Friday

We’ll have a docs-focused bug scrub Friday, Oct. 7 2016 14:00 CDT in the #docs Slack channel, for anyone interested in contributing. We’ll focus on the needs-docs keyword first, then on the docs focus if there’s time.

#4-7, #inline-docs

Summary for Helphub Meeting 12 July


@atachibana @carlalberto @greensteph @sarassassin @bethannon1 @juhise @normalize @geoffreyshilling @karys @justingreerbbi @adamsilverstein @Kenshino attended

Migration Updates

@geoffreyshilling @juhise @normalize reports that they are actively migrating articles. @atachibana will be finishing up his portion of the migration and will head towards migrating the WordPress Version articles

If migrators see any theme function related articles, they should do the following

  1. Leave a short explanation on the subject matter
  2. Leave a link towards the theme handbook on Devhub eg. https://developer.wordpress.org/themes/functionality/sidebars/

@Kenshino reminded all migrators to replace Codex links with Devhub links (when applicable).

Design Updates

@greensteph has partially finished the single view of the WP Versions Custom Post Type. It looks great and she’ll be continuing her work here https://wp-commhub.mybalsamiq.com/projects/helphub/WordPress%20Versions

It was suggested to strip the empty headings off the single article view so the article could concisely show what was changed.

@Kenshino suggested that stripping made sense, however, creating a section that lists Components that were not updated would be more inclusive.

@adamsilverstein enlightened us how the WP Versions (current) Codex articles are created. This will surely help to drive design decisions.

Development Updates

The WordPress Versions CPT was created and added onto wp-helphub.com.

wp-helphub.com was updated with the fixed versions of Helphub Post Type and Read Time. So migrators should stop seeing any warnings/notices that makes migration hard.

@carlalberto and @Kenshino will be working on the templates and styles for WordPress Version archive and single pages.

Codex Translations – how can we be inclusive?

Redirecting the English articles effectively makes any translate Codex articles tough to find.

A provisional decision was made to put a deprecated notice on the English articles for users to be manually directed to the new Helphub articles. This will give time for the translation editors to find a best solution for their community.

After a given amount of time, the auto redirection will be put in.

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


Codex Migration project update


When the docs team embarked on the Codex Migration project at the WCEU contributor day in June 2015, it seemed like a daunting, never-ending task.

The goal was simple: move away from using the Codex as the canonical reference for developer docs to a newly-established “Developer Hub”. The bulk of the documentation would be parsed from the WordPress source and be supplemented with some manually curated documentation along with user-contributed notes (examples).

There were a lot of reasons for why the Codex migration project was launched, the most prominent being that the Codex had reach an un-maintainable state as a manually curated community reference. Now a year later, we’re well on our way toward completely migrating all function references from the Codex to the Code Reference.

Side note: The HelpHub project also falls under “Codex Migration”, but more on the user and support docs end of the spectrum. Check out the HelpHub project page for information on contributing that effort.

Examples Migration

It all started with the examples.

Over the last year, 15 or so contributors manually migrated more than 1,100 function examples to the Code Reference and submitted them to the moderation queue as user-contributed notes.

Before approval, each example was individually evaluated for accuracy, completeness, and security by about 10 trusted reviewers from throughout the community. I approved the last of the migrated examples just a few weeks ago.

Content Migration and Redirection

With mixed feedback from the community, we’ve started the long process of redirecting the more than 1,200 function references from the Codex. Like the examples, each redirection is happening manually; there’s no automation here.

Great care is being taken to ensure that any useful (and accurate) information in the Codex makes the move too, either through direct improvements to the inline docs or by being brought over to the “More Information” section of each reference page.

Side note: we’re already seeing some of the “More Information” sections getting to be pretty long in some cases, and are looking into implementing some in-page navigation to make discovery a little easier.

Thank You Contributors

At this point, I’d like to send out thanks go to all of our contributors so far: @adamsilverstein, @atachibana, @bford2here, @bhlarsen, @boogawooga, @cmmarslender, @DBrumbaugh10Up, @hearvox, @helen, @ishulev, @marcomartins, @mcadwell, @morganestes, @mrsipstenu, @ninnypants, @rabmalin, @stevegrunwell, @sudar, @theMikeD, @tott, @vlastuin, @webdevmattcrom, @znowebdev

Special thanks also go of course to @samuelsidler and @siobhan for their steadfast support in getting this project off the ground in the first place, and to @coffee2code for managing the bulk of the infrastructure, special requests, and development of features in getting us this far.

We Need Your Help

According to the progress graph, approximately 160 function references have already been migrated and redirected. There are another ~900 still to be moved. If we follow a strict regimen of migrating at least 10 references a day for the next 3 months we should be able to complete the function reference section of the Codex Migration project. Of course that still leaves class and hook references, but one thing at a time 😅

It’s doable, but I probably shouldn’t try to do it all myself without a little bit of help. If you’re reading this and thinking, “Boy, I think I can help with this,” pipe up in the comments below or ping me on Slack at @drew in the #docs channel.

We’re over the hump, but there’s a long way to go. More frequent status updates will follow.

#codex-migration, #examples