Clarify Note in aria-brailleroledescription/braillelabel

[carmacleod]

A Note in aria-brailleroledescription (and aria-braillelabel) has a sentence that says:

It is very important to note that when using aria-brailleroledescription authors are solely responsible to align the attribute value with the document language and clearly communicate the use of this attribute to the user.

How does an author "clearly communicate the use of this attribute to the user"?
The note says "It is very important", and yet, as an author, I have no idea how to do this.

[pkra]

@carmacleod I've been circling around this for a while now and I'd say "it depends" but really I'm not sure we can know what is a good pattern for doing so before we see actual use. A bit of a chicken and egg problem.

Some ideas for different use cases

• A one-off button. Here, I think a description might be sufficient (if any is needed, see the code example).
• A long form document with recurring use of aria-braille* properties (e.g., a text about chemistry containing skeletal formulas as navigable SVGs with braille-labels containing braille chemical notation). Here, I think it could be sufficient if the use of aria-braille* properties is explained in an introduction, e.g., as part of a discussion of the visual interpretation of skeletal formulas. It could additionally be an alert when the reader enters via a deep link.
• A role=application situation, e.g., a web based sheet music editor leveraging music braille. Here, the information could be presented alongside other instructions on using the editor or via descriptions on UI elements (e.g., a button to add a note); there might even be user settings to change braille output.

I think these kinds of examples seem to fit better outside the specification so I'm not sure what to do to address your question.

Maybe we should talk F2F with a small subset of the group?

[pkra]

@carmacleod sorry for missing your +1 reaction. If I understand your reaction correctly, this issue can be closed and potentially another issue can be opened elsewhere - happy to for any recommendations as to where this kind of information fits.

[carmacleod]

Hi, @pkra. I guess my +1 meant "ok, I get it now". :)

I wonder if it would have been clearer initially if it had been split into 2 sentences. Also, we could add a (vague, but hopefully helpful) example to the "clearly communicate" sentence. Maybe something like:

It is very important to note that when using aria-brailleroledescription, authors are solely responsible for localizing the attribute value so that it aligns with the document language.

In addition, authors need to design a way to clearly communicate the use of this attribute to the user. For example, this could be in an aria-description, or in a section referenced by aria-details, or as part of the product documentation.

[pkra]

Thanks for the helpful suggestion, @carmacleod! I'll prep a PR.