Add in help into editor itself

[karmatosed]

This will come as we have docs, but because of the new nature of the interface and breaking of some existing mental models, would not having help be good sooner? Where it goes and how it looks would be a matter of discussion, but I think having some way to avoid people being so easily lost would be great.

[karmatosed]

Got feedback from @DrewAPicture regarding this - thanks! Copying here as given in Slack:

Just talked to @nylen and I think the best possible option would be to bring the help text into the UI directly.

Pretty much the only place we already do this in some form is in the image editor, which, outside of having a ready opinion from the a11y folks, I’d say is the closest thing to what I’d imagine we could repurpose elsewhere in the admin.

https://cl.ly/1T1v3w2r2f35

https://cl.ly/3A3I2C0Z3W2H

So best suggestion for moving forward would be to consult with @afercia and the a11y team and make sure whichever kind of inline solution you’re looking at, such as inline contextual help, expanding panels, or even tooltips that they pass wcag requirements.

[jnylen]

@karmatosed Might have misstagged the person there.

[karmatosed]

@jnylen yes auto pinging happened so apologies on that front.

[afercia]

FWIW, a while ago in the accessibility team we've discussed to consider to introduce some sort of "inline help" in core. See https://wordpress.slack.com/archives/accessibility/p1420678367000781

That was more related to the progressive removal of the title attributes from the admin screens, but I think it may apply here too. Having an immediate help available close to the feature users are going to use would probably benefit all users. Of course, it should be as simple as possible and easily discoverable.

[nylen]

@afercia when I was discussing this with @DrewAPicture a few days ago, he had some concerns about the accessibility of a tooltip or popover-based solution, like the one we worked on in #2217 (comment).

However, this has definitely been our preferred approach in Calypso, and likely would be here as well. Do you think that's generally acceptable from an a11y perspective? What can we be looking out for as we implement it?

[afercia]

@nylen as usual most of accessibility is about semantics, giving user proper feedback, predictable interaction, discoverability, device independence, etc. Looking at the example you mentioned:

The text "More info" wouldn't help so much. Imagine a page full of "More info", that would be basically the same issue of a page with plenty of "Read more" links.

Ideally, the text should be specific to the feature the help is about. Plain text is always the best option: "Help about xx feature". If that's not possible, a compromise could be expanding the text with an aria-label attribute. An icon with aria-label would be an option but, theoretically, icon-only controls would need tooltips.

From a functional perspective, the buttons + help in the image editor are a good example. They use a button element, they work with mouse and keyboard, and the help text is immediately after the button in the source (this is very important for screen reader users). Visually, whether the help it's an expandable panel or a "popover", doesn't matter so much.

The implementation in Calypso is different and not so accessible and I'd recommend to don't follow that pattern. The Help icon appears just on hover. It's a span. It doesn't work with a keyboard. The help text is injected before the closing </body> and thus is hardly discoverable for screen reader users.

[nylen]

the help text is immediately after the button in the source

FWIW, as of #2160 this is no longer true for our Popover component.

[afercia]

@nylen yep I see. It is now a developers responsibility to place the Popover immediately after the UI control that opens it. Ideally, this should be clearly explained in the readme.

Instead, the current readme (and also PostVisibility) show and use the Popover inside the button. That's definitely something to change. Will open an issue...

Edit: OK... I now see more clearly how it works. That's... not so ideal 😞 I've created #2306 for this.

[afercia]

@nylen seems to me EnableTrackingPrompt doesn't work any longer: clicking on "More info" doesn't do anything.

[karmatosed]

Adding a full help system feels out of context for v1. That all said, it's not something I want to forget. I am moving it into documentation as a project. We may loop back around to doing before we release Gutenberg, however it's not a core part of the project.