Title: AH-O₂ – Breathing new life into admin help! Author: Chris Reynolds Published: December 9, 2013 Last modified: December 12, 2013 --- [ ](https://profiles.wordpress.org/jazzs3quence/) [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 9:06 pm _on_ December 9, 2013 Tags: admin help    # AH-O₂ – Breathing new life into admin help! I thought it was time to introduce ourselves. I’m Chris, aka [@jazzs3quence](https://profiles.wordpress.org/jazzs3quence/), and I’m the project lead of AH-O_(2) — the project formerly known as Adminadmin (and super admin) Help. The AH-O_(2)/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](https://core.trac.wordpress.org/ticket/21583), 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](https://make.wordpress.org/ui/tag/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](https://make.wordpress.org/docs/2013/12/09/ah-o2-update-the-project-formerly-known-as-admin-help-9-december-2013/) 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_(2) project, stop by #wordpress-sfd. We meet on [Mondays at 17:30 UTC](https://www.timeanddate.com/worldclock/fixedtime.html?iso=20131209T1730) 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](https://make.wordpress.org/docs/tag/admin-help/). [#admin-help](https://make.wordpress.org/core/tag/admin-help/) ### Share this: * [ Threads ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=threads) * [ Mastodon ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=mastodon) * [ Bluesky ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=bluesky) * [ X ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=x) * [ Facebook ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=facebook) * [ LinkedIn ](https://make.wordpress.org/core/2013/12/09/ah-o-breathing-new-life-into-admin-help/?share=linkedin) 1. ![](https://secure.gravatar.com/avatar/dd39b1f3871667f7de435e7cf8878a5dca420111b138b13231563481a5f8e0d7? s=32&d=mm&r=g) 2. [centomila](https://profiles.wordpress.org/centomila/) 1:23 am _on_ December 10, 2013 3. I personally never use the help function, but I’d like to propose an alternative solution based on an “help mode”. 4. A checkbox (instead of the actual dropdown), to enable help balloons. If you hover the mouse cursor on a button (or form, checkbox, whatever need help) a simple balloon appear. 5. Something like this (random ugly image from google): 6. [http://static.flickr.com/29/61998339_9559d945d0_o.png](http://static.flickr.com/29/61998339_9559d945d0_o.png) 7. ot: i suppose this is not the best way to propose ideas and i apologize if i ignored the blogblog (versus network, site) and wordpress community rules. Sometimes, the desire to tell an idea, brings out of control. 8. ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) 9. [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 3:09 am _on_ December 10, 2013 10. > A checkbox (instead of the actual dropdown), to enable help balloons. 11. This is exactly what we are doing. The checkbox(es) live on your user profile page as seen in the last screenshot in this post and the tooltips that appear when you hover over something that has them is shown in the screenshot above that. 12. In addition to that, we are also adding a help overview describing what the page is for. Both of these things can be disabled. 13. ![](https://secure.gravatar.com/avatar/f470a1341315349e1006b505406c94c28eb6f74b48c25e9cc5273cb5d7cebc7c? s=32&d=mm&r=g) 14. [Matthew Denton](https://profiles.wordpress.org/mdbitz/) 2:32 pm _on_ December 10, 2013 15. Hey Chris, I can help out on development, was looking at the latest P2P2 A [free theme for WordPress](http://p2theme.com/), known for front-end posting, used by WordPress for development updates and project management. See our [main development blog](https://make.wordpress.org/core/) and [other workgroup blogs](https://make.wordpress.org/). notes with Tasks. If you could send me some additional details on where the project stands and if any other project members are integrating the code from @ninnypants that would be great. 16. * ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) * [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 4:16 pm _on_ December 10, 2013 * Thank you, sir. You’ve got mail. 17. ![](https://secure.gravatar.com/avatar/97d8cbacd8eb803d9718f5c18bd36dc3b652c75e1e08f633bc2f7c501f82b173? s=32&d=mm&r=g) 18. [Anup Biswas](https://profiles.wordpress.org/upamahin/) 9:26 am _on_ December 11, 2013 19. Hey Chris, I have requirement in new WordPress version. If there there is hook and filterFilter Filters are one of the two types of Hooks [https://codex.wordpress.org/Plugin_API/Hooks](https://codex.wordpress.org/Plugin_API/Hooks). They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. for wp-adminadmin (and super admin)/nav-menus.php to add new tab and some additional functionality for advance menu operation. 20. i have no idea where i post about this type off topics. 21. * ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) * [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 3:02 pm _on_ December 11, 2013 * If it hasn’t already been suggested (which is possible), you’d want to open a new TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. for a feature requestfeature request A feature request should generally begin the process in the ideas forum, on a mailing list, as a plugin, or brought to the attention of the core team, such as through scope meetings held for each major release. Unsolicited tickets of this variety are typically, therefore, discouraged.: [https://core.trac.wordpress.org/newticket](https://core.trac.wordpress.org/newticket) * But do a search to see if someone else has suggested that before creating a new ticket: [https://core.trac.wordpress.org/report](https://core.trac.wordpress.org/report) * That said, the AH-O_(2) project will be looking at this stuff, too, so we’ll definitely keep theme and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory [https://wordpress.org/plugins/](https://wordpress.org/plugins/) or can be cost-based plugin from a third-party. developers in mind to allow them to easily add new help content. 22. ![](https://secure.gravatar.com/avatar/37509e39311b0e115b5589c05fd1ca53ee1c434dfc10ec718ec44de1fedefe64? s=32&d=mm&r=g) 23. [Vasu Chawla](https://profiles.wordpress.org/vchawla26/) 11:05 am _on_ December 12, 2013 24. I actually liked this idea of “new users will get an overview at the top of every page”. Extending this, I would like to say that, the overview box at top can have a hde option, clicking which the overview button gets hidden(abviously) and a pop-up/tooltip auto-appears at the same time,on the help button, to notify the user that this is where the help is…and, for future cases…the same tool-tip appears after every interval., or if the user is no a page, doing nothing for a specific time…makes sense ? Please point me, if I made any mistake,,,I am kinda new to this community 🙂 25. * ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) * [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 5:44 pm _on_ December 12, 2013 * We’re planning on having a dismiss button (I think) but you will also be able to deactivate the help messages entirely. There will still be a help link in the adminadmin (and super admin) next to the screen options tab styled to match whatever CEUX ends up doing with screen options. * Tooltips are controlled separately (at least the ones that appear when you hover over something — you’re thinking of the pointers, I think, and we don’t have plans, at this time, to implement those) and will be enabled for everyone by default. 26. ![](https://secure.gravatar.com/avatar/2438d3fe7668a56783a3c70166e413688270a5797b8be589884bbd172b6385b3? s=32&d=mm&r=g) 27. [Zoe Rooney](https://profiles.wordpress.org/zoerooney/) 4:27 am _on_ December 14, 2013 28. In addition to the locations you’ve already mentioned for the adminadmin (and super admin) help access, what about adding a link underneath Dashboard in the menu, in the vicinity of the Updates item? I’m not at all sure how often people view that menu, but perhap worth exploring a bit? 29. * ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) * [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 4:39 am _on_ December 14, 2013 * That was something we talked about, too. Personally, I’m against that idea. I don’t know how much more visibility it would really get being put in the dashboard menu unless we gave it a top-level menu item. And giving help a top- level menu is basically saying “this stuff is more important than that other stuff”…unless you put it at the bottom, under Settings, where it’s also not going to be seen. Arguably, Help should be the most important thing BUT it should also be out of the way and not annoying to people who don’t want it ( see Jetpack and Mark Jaquith’s [Menu Humility](https://wordpress.org/plugins/menu-humility/)). - ![](https://secure.gravatar.com/avatar/2438d3fe7668a56783a3c70166e413688270a5797b8be589884bbd172b6385b3? s=32&d=mm&r=g) - [Zoe Rooney](https://profiles.wordpress.org/zoerooney/) 2:58 pm _on_ December 15, 2013 - I definitely don’t think it should be a top level menu item and I guess there isn’t a single central help page for a menu item anyway (I think?), but I do think a secondary menu item might help. - It would certainly require testing to verify, especially since I’m not sure how much time newer users spend on the Dashboard menu item specifically. Particularly with the icon-only sizes, I’m betting newer users are probably skimming the submenu text quite a lot to get where they want to go. I’m just thinking that seeing “Help” there may catch some eyes. * ![](https://secure.gravatar.com/avatar/d6d6254d551f10047c16ac27288de32bfa5d96a399f1bcf618ac6b49656424f7? s=32&d=mm&r=g) * [Chris Reynolds](https://profiles.wordpress.org/jazzs3quence/) 3:41 pm _on_ December 15, 2013 * In our early user testing, it did seem like people hovered over all the sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. menu items to figure out what they needed to do and where they needed to go. _However_ the best idea as far as putting help in the menus that we had was to put a Help submenu under each top level menu. But there’s no guarantee that anyone would click this. We believe that putting the help in front of people rather than having them look for it is the best solution. That said, we can do testing when it’s ready to confirm this. * My suspicion is if we put Help anywhere in any menu, people will just ignore it because, generally speaking, people don’t _want_ to click on a Help link, they want to figure it out on their own. And we’re so accustomed to poorly implemented help systems that we just don’t use them, expecting them to be bad. 30. ![](https://secure.gravatar.com/avatar/2438d3fe7668a56783a3c70166e413688270a5797b8be589884bbd172b6385b3? s=32&d=mm&r=g) 31. [Zoe Rooney](https://profiles.wordpress.org/zoerooney/) 5:17 pm _on_ December 16, 2013 32. That’s an interesting point about people not wanting to click on a help link. Would be interesting, along with testing if such a link as a submenu item, to test if different wording impacts usage. Such as “User Guide” or something… Anyway, just brainstorming after reading in the post that the on-screen help (and tests with adminadmin (and super admin) bar help link) seems to go unnoticed, which is my experience with both “help” and “screen options.” Comments are closed. # Post navigation [← Search Initiative Chat Recap](https://make.wordpress.org/core/2013/12/09/search-initiative-chat-recap/) [Metamorphosis Meeting Update →](https://make.wordpress.org/core/2013/12/11/metamorphosis-meeting-update/)