I thought it was time to introduce ourselves.

I’m Chris, aka @jazzs3quence, and I’m the project lead of AH-O₂ — the project formerly known as Adminadmin (and super admin) Help. The AH-O₂/admin help team has been quietly meeting every Monday since the end of August to try to reimagine the help system in the WordPress admin.

The Problem

The biggest issue we are trying to solve is discoverability and accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) (not a11yAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility), specifically — though that is something we want to look at, too — just the ability to easily access and use help when you need it). We did some research to look at what other systems were doing in terms of admin help and we user tested early on to try to establish how easy/hard it was to find help in the WordPress admin when it was needed. We asked users to perform some basic tasks (write a post, change the theme, add/change a widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user., etc) to see if they were able to complete them without issues, and if/when they did have problems, how they chose to solve them. Uniformly, no one found the help and some users went to Google to find the answer instead of clicking the Help tab.

After that, we tried some basic tweaks. Moving the Help tab to the admin bar had been suggested in Trac, however, in our testing, it proved to be no better a solution for discoverability — and, on the contrary, users who are also using LastPass could have the admin bar completely concealed behind the “Save Password” bar that LastPass throws into the top of the page (and there may be other, similar browser extensions that do the same thing), meaning, to those users, the help button may as well not exist.

So we tried doing something more obvious — simply changing the color of the tab improved discoverability. But it doesn’t look very good. The CEUX project is rethinking those tabs, anyway, so our plan is to take their lead and make the tab a link with an icon next to Screen Options rather than trying to propose some radical new design. But, in addition to that, we’re adding a few new things…

The Solution

We’re approaching this from a couple different angles. The first is moving the help link out of the tab and style it the same as screen options. But beyond that, new users will get an overview at the top of every page, similar to the welcome box on the dashboard:

We’re also going to add tooltips that appear when you hover over a new help icon that will display next to some of the actionable items:

(The jury is still out on whether tooltips or modals work better — we ran a survey/UXUX User experience test and tooltips just barely edged out modals. Our plan is to actually do user testing on both when we get to that point and see which actually performs better for actual humans.)

These are both controlled by new usermeta settings that are added to the profile page (meaning they can be turned off):

Additionally, the admin help overview boxes will have a link that takes the user to their profile page so they can edit their help settings.

We need you!

Progress on this has been slow but steady. I had originally hoped — when I became the project lead — that we could be done by now so this could be proposed for inclusion in 3.8. We’re currently shooting for 4.0 which should give us lots of time to test this stuff.

The main need has been devs (who have time). We have a few, but everyone is busy with other stuff. @ninnypants has done quite a bit of js stuff, and we have a few front end designers/devs, but where we could use the most help is in grunt work. I’ve outlined our immediate tasks in my latest P2 post on the make/docs blogblog (versus network, site).

Once the heavy lifting is done, the rest will be fairly easy — it will mainly be a matter of filling in all the documentation that are going to go into the containers we’re building for them. At that point, the barrier to entry for helping the project goes way down — it should be easy to get folks up to speed on what would need to be done to add text at that point. And then we can get nit-picky about the actual documentation we’re adding — if it’s a straight copy pasta from current WordPress admin or if it needs to be updated first or written entirely from scratch. And the tooltips will (almost definitely) need to be written from scratch.

If you’re interested in helping the help AH-O₂ project, stop by #wordpress-sfd. We meet on Mondays at 17:30 UTC and notes and updates are kept on make/docs with the tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) admin help.

#admin-help