Customizer: Improve help text for Additional CSS

[mizejewski]

This is about flawed documentation.

The helper text provided is not helpful. In fact, I'm not even sure what half of it means.

Linking to a clear and simple definitions/background page is a good idea, but this top level should only have an example or instruction about what to actually type in the field.

[westonruter]

What would make sense to you?

BTW, it looks like you're also using Jetpack which extends Additional CSS with a CodeMirror code editor.

[mizejewski]

Hi @westonruter

Yes, I finally managed to turn on the now hidden Custom CSS thanks to ​https://wordpress.org/support/topic/jetpack-custom-css-2/#post-9122448

I think the helper text could be simplified, but I honestly don't know what all that Tab and Esc stuff is even about. And is it important enough to be mentioned there?

If I were to rewrite it keeping a novice CSS author in mind, I'd suggest:

Customize the appearance and layout of your site with CSS code tied to this theme.

​Learn more about CSS

/*
Add your own CSS here (after the backslash below)
*/

Thanks for considering

[westonruter]

@mizejewski all of that text is there for the sake of accessibility. For users using assistive technologies, the help text is explaining how to interact with the field.

[mizejewski]

Replying to westonruter:

@mizejewski all of that text is there for the sake of accessibility. For users using assistive technologies, the help text is explaining how to interact with the field.

Accessibility is important, but I didn't find it clear as written.

Here's another approach (assuming there's a good page to link to)

Customize the appearance and layout of your site with CSS code tied to this theme.
​Get accessibility tips

​Learn more about CSS

/*
Add your own CSS here (after the backslash below)
*/

---

Or another idea:

Customize the appearance and layout of your site with CSS code tied to this theme. No mouse? brief sentence with accessibility tips...

​Learn more about CSS

/*
Add your own CSS here (after the backslash below)
*/

[westonruter]

I'll defer to UX and accessibility experts on the best wording here.

[mizejewski]

Agreed -- I'm coming from the UX angle, but input from an accessibility expert would be good here.

[joedolson]

It's a difficult issue to convey, but I'm not sure there's an easy way to reduce that text. The issue is that the normal mode of moving from one field to the next when using a screen reader or a keyboard is to hit 'Tab'. Since the 'Tab' key is needed in the CSS editor to enter the tab character, it can't be used for navigation. There isn't any standard for how to navigate using an alternate key, so we need to be able to explain how somebody can get out of the CSS editor if they need to use a keyboard.

On reading the text several times, I think it's going to be unclear for non-keyboard dependent users because they won't understand why it's needed, so they would need sufficient background information to understand that this instruction is not pertinent to their usage. However, it's perfectly clear for somebody who is keyboard dependent and needs the instruction.

One thing I'd suggest as a possibility is if each panel had an optional toggle to enable notes on keyboard functions if they are available. This would have three advantages that I can see:

1) The keyboard notes wouldn't be visible by default, so would make the default design and layout cleaner.
2) There would be a system in place for communicating any needed keyboard-specific information (such as shortcuts) that were relevant to a specific panel. This would constitute context-specific help, so people wouldn't generally need to comb through a large quantity of information to find what was relevant to them.
3) Because the keyboard information toggle would itself be a tab stop, somebody who needs keyboard information would have the presence of additional keyboard information brought to their attention while navigating. Right now, it's only available while reading. While this is a minor distinction, if somebody was navigating quickly using a screen reader, it would be easy to tab into the CSS editor without having read the instructions on how to escape it.

Any way, those are some thoughts on this.

[afercia]

A dedicated "Help" control to toggle some help for keyboard users seems an interesting idea to me. Maybe something to explore also in other parts of the Customizer and the WordPress admin.

Worth noting a similar text is used also for the Theme and Plugin editor textarea, in the related Help tab:

I wouldn't say this is a bug though. An enhancement to the wording and a dedicated Help could certainly help.

Something very easy to try, off the top of my head, could be separating the help text in two different paragraphs and prepending "When using the keyboard:" (or similar wording) to the second paragraph:

When using the keyboard: In the editing area the Tab key enters ...

[melchoyce]

Working on this in the CodeMirror project on GitHub: ​https://github.com/WordPress/codemirror-wp/issues/36

[afercia]

@melchoyce @westonruter can this be closed now that Additional CSS has an auto-expanding help section (expanded when there's no CSS content)?

[westonruter]

Yes. I must have neglected to tag this ticket as being fixed. See r41376.