AH-O₂ Update — 3 March, 2014

Help Overview refactoring
@brainfork has been ill and was unable to work on this this week. @jazzs3quence created tickets for some of the issues that were reported in https://github.com/jazzsequence/WordPress-Admin-Help/issues/50 many of which were things that @brainfork was planning to work on. See:

@clorith is going to work on refactoring the tooltip structure a bit to make it more flexible for devs and give us more options for tooltip styles.
@trishasalas will be working on some new styles for the tooltips
Between the two of them, we’re hoping to nail:

Admin Help Inventory spreadsheet
@ubernaut has added tooltip locations to the Pages admin pages in the spreadsheet we’re using to keep track of such things. He will work on adding the actual TinyMCE formatting buttons this week.

Target Date
We’ve set a tentative target date for April 1. This will give us time to test the plugin and fix any issues before the discussion begins about WordPress 4.0 feature plugins.

Help wanted!
To meet this target, we need help:

  • adding tooltips — though this process may be changing, the changes should make things easier and we can help with the transition — mostly we need new tooltips to be added (or at least written) for all the elements (that have not been added already) in the spreadsheet (or for anything else that’s missing that isn’t included)
  • testers — we’d love to have more testers look at this and let us know if/when they find any issues

If either of these things sound like ways in which you could contribute, you can let us know in the Google Group, in the comments of this post, or in our Monday meeting.

Our next meeting is next Monday 18:30UTC.

#admin-help, #ah-o2

AH-O₂ Update — 24 February, 2014

Help Overview refactoring
@brainfork was going to work on this but didn’t have the time. He was able to review the code though, but no progress has been made. @trishasalas has stepped up to help out with this. They will be taking a look at the issues reported in this ticket (moving help footer over) as well as this ticket (text next to dashicons are not aligned vertically) and creating new tickets for any other issues that come up.

Tooltip hover delay
@clorith reported that the tooltips were sometimes taking the focus away from the actual item. he then submitted a pull request which has been merged that increases the hover delay. This will be included in the next version in the WordPress.org repository.

Tooltip arrow positioning
…is still an issue for some tooltips which is mostly to do with not having good selectors to work with (not everything in the WordPress admin has IDs or classes associated with them). @trishasalas is going to look at this, but since this could be done completely differently in core by just adding more specific ids to the things that need tooltips, I’ve given it a lower priority. @trishasalas may try to do at least one admin page, though, as a proof-of-concept.

Because I can’t consider this plugin “done” (and therefore 1.0) until tooltips are on every page, and because we’re going to run out of digits if we keep going at the 0.x rate for every weekly update, and because looking at a plugin in the repo that has a 0.x version looks less like a completed entity than a 1.x release, we’ve agreed to tweak how the versioning is handled a bit to make better use of minor point release versions. Updates with minor fixes or new tooltips will be considered a 0.0.x release, more significant changes will be a 0.x release. There was some discussion about this that can be read in the logs, but the main reasoning is that it seems misleading to call something a 1.0 if it’s still incomplete (in this case, missing tooltips) and we’d be at a 1.0 in 4 weeks at our current rate.

Admin Help Inventory spreadsheet
@ubernaut will work on tackling the Pages…pages next in the spreadsheet having just finished filling out the Network Admin screens.

@nikv has started work on adding tooltips to the comments page but that has not been merged into the plugin yet.

Tooltips on Mobile
We’ve decided to go with the tap-and-hold interaction for tooltips on mobile devices. This takes a lower priority to getting the tooltips in and no work has been done on it yet, but if someone would like to tackle it, let us know by commenting in the open ticket here: https://github.com/jazzsequence/WordPress-Admin-Help/issues/32

The logging bot was having a fit, so here’s my copy of the logs from the meeting (the first 15 minutes are cut off, unfortunately): http://s3q.us/log/ah-o2-log-2014-02-24.html

#admin-help, #ah-o2

AH-O₂ Update — 17 February, 2014

We’ll be releasing 0.7 this week. New in this update are initial tooltips for the sidebar menu items & tooltips on the Users pages.

@brainfork Will be working on reworking the help overviews. This partially came out of this ticket, where it was determined that a restructure of how the overviews are marked up may be necessary.

@ubernaut will continue to work on the spreadsheet with a focus on identifying areas for new tooltips. This makes it easier when adding the tooltips in the plugin to know where best to place them. The next area for focus for the spreadsheet will be the Network Admin screens. I recently opened the document up to anyone with a link to make it easier for people to jump in, flesh out areas that are bare, or claim admin pages to add tooltips to without requiring an owner to invite them to be able to edit the spreadsheet.

@nikv has volunteered to help out with adding tooltips also.

I’ve updated the tooltip documentation somewhat to add some additional details/guidance for adding new tooltips. Feedback (or edits) are welcome.

One thing that wasn’t discussed this week (although there’s a ticket) is the fact that the arrow location for some tooltips is pointing to the wrong place. My suspicion is that this is largely a CSS issue (or an issue that can be solved with CSS) and anyone who wants to jump in and take a stab at that is welcome. There are a variety of places where this is the case and may need to be styled individually. The main issue is a lack of specific IDs/classes to hook the tooltips onto, which could be conceivably solved in core by adding specific classes/ids to those elements.

Our next meeting will be next Monday 18:30UTC

#admin-help, #ah-o2

AH-O₂ Update — 10 February 2014

a11y and title attributes

It was discussed last week at the meeting — and subsequently added to the plugin — that we would take the title attributes of linked elements that had them by default, so that in the future, adding tooltips to these things could be handled the same way they already were. However, since @grahamarmfield’s extensive review indicated that this may be a problem for screen readers, as well as the fact that core will be removing them, this behavior has been removed and will no longer be present in the next (or future) iteration. (Graham, if you want to run the updated (0.6.0) plugin through your screen reader program(s) that would be greatly appreciated 🙂 )

Tooltip pointer positioning

There are some tooltips that have somewhat “iffy” pointer positions. There are various reasons for this, but the biggest one is specificity. If we were editing core, we could add our own classes or IDs and then target things specifically, then add a tooltip to those handles. Since we aren’t, and there are some elements that don’t have their own specific wrappers (for example, some column headings), we just do the best we can. (See https://github.com/jazzsequence/WordPress-Admin-Help/issues/45 for some examples). We may come back to these later and add CSS to the pointers so they can be moved specifically for those tooltips. Moving forward, if there’s a commit adding a tooltip where this is the case, we’ll be tagging this ticket so we can keep a general record of the tooltips that are having this issue.

What we’re working on

We are primarily focusing on the task of adding tooltips to the plugin at this point. While it is acknowledged that the actual help overview content may not be the best for an always-on (at least for some users) space that is not accessed via the help tabs, without enough interest in helping write new content for these overviews, we’ve had to move on to the more pressing task of focusing on the tooltips, all of which will be entirely new (rather than being able to pull in existing content in one form or another).

@brainfork will also be looking into adding tooltips to the sidebar menu items using a global tooltip doc and js file.

@zoerooney and @ubernaut will be working on updating the admin pages spreadsheet with a particular focus on identifying areas for tooltips. I’ve made this editable to anyone with a link to give more people an opportunity to contribute to this document (which hopefully won’t be a problem).

Testers and contributors are welcome — report any issues here: https://github.com/jazzsequence/WordPress-Admin-Help/issues?state=open

Pull requests are also appreciated!

As a reminder, our meeting time has changed from the time listed on the sidebar. Our next meeting will be next Monday 18:30UTC.

#admin-help, #ah-o2

AH-O₂ Update — 3 February 2014

@jazzs3quence added a few tooltips to the Users pages. Adding new tooltips is pretty easy, but we may want to revisit our documentation to clarify some things
@brainfork closed out a few tickets, including positioning the tooltips so they aren’t bouncing around and setting the anchor tag title attributes to be the tooltip content where applicable (as opposed to our own custom tooltip content).

We still need testers and documentors as well as volunteers to help add tooltips. All of these tasks are pretty simple and should only require a few minutes of instruction. The plugin in the wp.org repo should get updated tomorrow with this week’s commits.

@jazzs3quence also created a page on github that’s a bit more friendly to non-techy peeps who want to just get the information and/or download the latest version (before it makes it to .org). That page is here: http://jazzsequence.github.io/WordPress-Admin-Help/

#admin-help, #ah-o2

AH-O₂ Update — 27 January, 2014

The new time threw me and I ended up starting the meeting a half hour early. Apologies to anyone who may have arrived *on time* who ended up missing the first half hour of the meeting.

This week there were some significant contributions from @mdbitz for the help overviews, @trishasalas for the tooltip styling and @brainfork and @mdbitz for new tooltips. We also have some documentation now for adding new tooltips. Most things are now functionally in place and we’re just trying to fill in the gaps.

GitHub repo contributors

I didn’t realize this was possible until @trishasalas pointed it out, but I added some folks on as contributors to the project repo on GitHub. This essentially gives them commit/merge access but it also means I can assign tickets directly to specific people/contributors. If you are interested in jumping in and would like to be added as a contributor, let me know, but I think I got everyone who’s been submitting pull requests thus far. (Pull request can still be submitted normally, the only real difference is I’m not the only one able to merge them in and/or able to push commits to the repo.)

Tooltips on mobile?

I’ve opened a ticket to discuss how to (and whether we should) handle tooltips on mobile devices. My feeling is that the value of the tooltips is discovering them accidentally when you are trying to do something and mousing around the screen. User interaction on touch devices doesn’t work the same, and any kind of interaction that would generate a tooltip that I can think of would involve more intentional interaction with the interface, which defeats the purpose to me. I’m open to other ideas, though, if anyone has them. https://github.com/jazzsequence/WordPress-Admin-Help/issues/32

New tooltips

The plugins pages should have tooltips on them now (including the subpages), so we’re going to start working through the list of admin pages to add tooltips to. Now that we have documentation on how to add them, I would like everybody on the team (and anyone else interested) to try taking an admin page and start adding tooltips. We’ll use the spreadsheet to mark what’s been done and what needs to be done as well as allow people to claim pages so we aren’t stepping on each others’ toes. This will also draw more attention to the documentation we have, and whether it needs to be updated (and to what extent it should be updated). The more people we have working on these, the faster we’ll be done, and this is the biggest chunk of work in front of us right now.

On that note, we’re going to be looking into adding tooltips to the admin sidebar. One thing I was thinking about from testing was how a lot of people would move their mouse around the screen looking for things to pop out at them to guide them to their task. A tooltip that appeared over “Appearance”, for example, could explain that that’s where you go to change the look and feel of your site which might otherwise be (and was) ambiguous to some users.

Known Issues

There are a number of issues we’re currently working on fixes for, but there’s probably a lot more we aren’t aware of. If you are testing the plugin and are having some issue that hasn’t been reported already, please create a ticket for us on Github so we can look at it. Make sure you check the closed tickets as well as there may be some tickets that got closed for one reason or another.

I’ve created a number of tags to filter different types of tickets. This list is growing, but hopefully can give a casual observer a frame of reference in terms of what we might need help on and in what context:

needs testing means we need another pair of eyes on it to confirm that it is a) is happening for more than just the person reporting the issue and b) under what circumstances the issue can be reproduced. This status may also be used later for issues that have been fixed but need confirmation that the fix is working. These tickets are things where anyone is welcome to jump in and try to reproduce the issue and report back with their experience. The more information we have on these, the better.

question means the issue is open to the floor for feedback regarding how something can/should be handled. these may or may not be technical. anyone is welcome to put in their 2 cents.

priority-* refers to the priority of the ticket

wontfix means that, for whatever reason, this isn’t something that can be fixed. One example of a wontfix ticket is the $WP_Screen errors that appear with WP_DEBUG turned on. This was the only way we could pull in the existing help content without hacking core (and therefore is a non-issue if/when this gets merged into core). (If anyone has a better way to handle this, feel free to let us know.)

enhancements are tickets that will add some new functionality. unless assigned to someone, these are open to anyone who wants to jump in and comment or take ownership of that particular proposed functionality.

One issue that seems to resurfaced is that the add new tooltip on the plugins page is empty. I saw this early on but it seemed to fix itself and other people weren’t been able to reproduce it. It’s come back again for another tester, so we really need more testers to confirm to help us isolate this and try to figure out what’s up. Any assistance peeps can give is greatly appreciated.

How to contribute

The biggest things we’re looking for at this point in terms of contributing (if you aren’t comfortable working on adding in new tooltips) is testers trying to break stuff and people writing documentation. If you’d like to add documentation but not add in the tooltip or overview itself, you can create a ticket, paste your documentation in, and we can assign it to someone to add it to the plugin.

#admin-help, #ah-o2

AH-O₂ Update — 20 January, 2014

We had several people missing today, so the meeting was short. A few items of note:

Help Overview styling

The overviews have gotten some attention and now look a lot better. I believe there’s still more to be done to make these responsive, but they are now only showing based on your profile setting and are no longer weirdly centered (thanks @mdbitz!)

New tooltips

There aren’t any new tooltips on the plugins page, but a few were added to the Posts page, for your viewing pleasure. Tooltips still need some styling, though.

New meeting time(?)

I’ve been asked if it would be possible to move our meeting time. I’m currently proposing a revised meeting time of Monday 18:30UTC unless there are any serious objections.

Cross-posting to UI

I’ve also been asked to post over on make/ui because we’re getting to the point where we might want — and benefit from — more exposure over there. I’ll still be posting here because we’re sort of a hybrid project and I still want to involve the docs team in the documentation side of things. Which leads me to…

Documentation for the documentation plugin!

We’ve started writing some docs on how to add docs to the plugin. @mdbitz (with the help of @jdgrimes) has written a doc covering the help overview (which is the part that’s refactoring the existing help tab). Anyone wanting to make changes to the content that is inside of the help overview that exists in AH-O2 should review this doc first to know how to do it.


We’re still working on getting documentation up for how to add tooltips and tooltip handles.

Testers wanted!

So, please help test! I’ve been reporting bugs as I see them, and we’ve seen some odd issues that only seem to happen in certain environments. The more people testing the plugin out the more we can confirm whether these are environment issues or actual bugs. Please report any bugs you find (or test out any of the bugs already reported and comment on the open tickets) here: https://github.com/jazzsequence/WordPress-Admin-Help/issues?state=open

#admin-help, #ah-o2

It’s been brought to my attention that I’ve…

It’s been brought to my attention that I’ve failed to put a link to the AH-O2 plugin in the WordPress.org repo (not once but twice, although there’s only really been one update since it was live in the .org plugins repository). So, I apologize. Anyone who wanted to download it can do so here:


Note: The 0.2 update hasn’t gone up yet, but I will try to do that today.

#admin-help, #ah-o2

AH-O₂ Update — 13 January 2014


  • New tooltips to the plugin stalled primarily because not everyone was familiar with the grunt workflow. Since this adds an additional learning curve just to get started with the project, we’re dropping grunt for now so the js files (and anything else) can be edited directly which should hopefully increase the speed at which we’re able to do stuff. Grunt may be added back in later to do final tasks (like minification) or if everyone ultimately gets up to speed on grunt and decides, collectively, to start using it again. @ninnypants is going to work on pulling out the grunt dependencies (which is mostly in which js files are being called) and will also work on writing a how to tutorial for people to get started wtih grunt.
  • @trishasalas wasn’t able to work on tooltip styling this week. @ubernaut is going to pick up working on applying some basic styles to the tooltips this week.
  • we’re going to try to add an AH-O2-specific css class to the .ui-tooltip element we’re creating. For now, though, we’re just going to use .ui-tooltip. Ultimately, if the jquery-ui style guide project that @helen started working on picks up some momentum and produces canonical css rules for jquery-ui components, we’ll just use that, but for now we’ll try to use something like .ui-tooltip.ah-o2 to make sure we aren’t clashing against anyone else’s .ui-tooltip styles. @ninnypants is going to work on adding in an AH-O2 class to our tooltips.

Help Overview

  • @mdbitz wasn’t in attendance today but did submit a pull request earlier in the week for his work on the help overviews. It was a branch off an older version of the source, but I was able to get it merged today and it will be included in the next update on WordPress.org.
  • the overviews are really rough in terms of styling, and I found some issues in how the screen options component was working (or not)
  • currently the overviews display existing help tab content. this is where we need help — writing new content to fill these containers. also:
  • Do we keep the tabs or turn those into tooltips or page-specific overviews? I’d like some feedback from folks who have worked on the current help system to help guide how we handle these moving forward. For now, I advised the team to add the tabs and we can always pull them out later.

Other stuff

  • I’ve started creating tickets in the GitHub repo for things that need to get done. Feel free to report any issues you find there: https://github.com/jazzsequence/WordPress-Admin-Help/issues
  • I also added some new tags to said tickets for priority to try to direct which issues are most important
  • We have a new banner for the WordPress.org repo thanks to @ubernaut. This will be added in the next update, also:

Ah02 2x

  • I should be able to get version 0.2 up tonight — I don’t think there’s anything else that I was waiting on that’s likely to be added before the next commit.
  • @ninnypants indicated that we should add define( 'SCRIPT_DEBUG', true ) to our wp-config.php files for adding new tooltips.

Next meeting will be next Monday 17:30UTC

#admin-help, #ah-o2

AH-O₂ Update — 6 January, 2013

Help Overview Update

  • @mdbitz shared some screenshots of what he’s working on earlier in the week. These screenshots are available in the Google Group. The code isn’t quite ready to be merged yet, so the initial release on WordPress.org will just be with the tooltips.
  • The current solution involves hacking core — @mdbitz is trying to get it so we can pull existing help tab content from WP_Screen into the new help overview containers in the plugin
  • The plugin will display the current help content (if it exists) for the current page, but can be overridden and new content added by the plugin
  • @mdbitz is also working on getting the overviews to work responsively. @trishasalas and @ubernaut both said they’d be willing to help with this, if needed.
  • @jazzs3quence will hide the profile option for the help overviews temporarily for the initial release

Docs input

We (still) need input from docs folks if things are going to be changed in terms of how the content is presented vs. what was proposed in the original mockups. For reference, the main points that have been discussed are here and here.

  • @nlarnold1 will attend the thursday meeting and talk to the docs team to start the discussion
  • @jazzs3quence will try to be there as well.


  • @ubernaut brought up the issue that tooltips may not be usable on touch devices. Is there a solution/workaround? How are other people/projects handling this?
  • keyboard shortcuts for a11y wouldn’t work, either, on touch devices
  • No new tooltip hotspots (for lack of a better word) have been added. The plugins pages do not have anything filled in in the spreadsheet
  • @ubernaut will work on filling out those areas first and pinging the Google Group
  • once that’s done, @brainfork can work on adding in those tooltip areas
  • @jazzs3quence can also help fill in the gaps in the spreadsheet so it’s not bottlenecking development

Updating and testing the plugin

  • @jazzs3quence suggested adding support for the Github Updater plugin for access to bleeding edge updates. This was ultimately overruled — not really necessary if the maximum amount of lag between .org updates is one week and if ppl want the latest latest version, they can get it from the Github repo.
  • .org plugin will be updated after the meeting, once a week
  • the first version of the plugin will be uploaded to WordPress.org today sometime

(Revised) Development Timeline

  • January 6 — AH-O2 to be added to wordpress.org/plugins
  • January 6 January 13 — initial help overview integration
  • January 13 — initial tooltips to be added for plugins pages
  • January 13 January 20 — initial tooltips to be added for all admin pages
  • January 20 — list of wants/needs from docs sub-team (this is on the outside, ideally we need this as soon as possible)
  • February 3 — first AH-O2 beta release
  • April 15 — tentative release date for WordPress 3.9, AH-O2 is fully tested and ready for inclusion in core.

Full IRC log

#admin-help, #ah-o2