aria-braille properties: improve authoring note

[pkra]

Adds clarifying language to the note for aria-braillelabel and
aria-brailleroledescription to help authors understand what they need
to consider when using these properties.

Closes #1205

[pkra]

To simplify the diffing:

Current version:

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

Proposed version

It is very important to note that when using aria-braillelabel 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.

(And the same change for aria-brailleRoleDescription.)

[carmacleod]

Looks good!
Thanks, @pkra !

[sinabahram]

I have some concerns over description or details being recommended, even as just an example, here. Will that not cause tons of unnecessary speech? Even something as short as "has braille" would be repeated per element? I like the reference to documentation, but I hesitate to call out description or details. Thoughts?

[pkra]

@sinabahram wrote

Will that not cause tons of unnecessary speech?

Right. In #1205 (comment) I had suggested a description for a one-off button use case. But it's probably too risky to write it this way here, i.e., developers might stop reading and use a description.

@carmacleod since I blatantly copied your suggestion from that thread, what do you think?

I'll think about other use cases that might be less problematic but I'd also be ok if the note only mentions (product) documentation as an example. Complex examples could still be done elsewhere.

[sinabahram]

for what it's worth, I vote to remove both description and details

[carmacleod]

@pkra

@carmacleod since I blatantly copied your suggestion from that thread, what do you think?

I agree that without the "one off" context, we shouldn't mention details or description.

So it's perfectly ok with me to have the note only mention product documentation.

Thanks for pointing this out, @sinabahram !

[pkra]

I've pushed a change to strip it down to: "For example, this could be done in the product documentation."

[sinabahram]

Awesome, approved on my end.

[cookiecrook]

Approved with or without, but consider added a note near the localization comment that braille users use different braille tables that don't always align with a language, so using literal braille characters should be avoided unless there is no other option.

[pkra]

@cookiecrook wrote:

Approved with or without, but consider added a note near the localization comment that braille users use different braille tables that don't always align with a language, so using literal braille characters should be avoided unless there is no other option.

Just to double check here's how the note currently starts:

Note that Assistive Technologies with braille support can convert aria-roledescription content to Braille. In addition, assistive technologies will be able to customize such braille output according to user preferences. Using only aria-roledescription is almost always the better user experience and authors are strongly discouraged from using aria-brailleroledescription to replicate aria-roledescription.

and ends with

This is even more important when the value consists of Unicode Braille Patterns because Assistive Technologies will pass such content directly to the user without applying user specific braille translations; in general, authors are strongly discouraged from using Unicode Braille Patterns in aria-brailleroledescription.

So the suggestion would be to add something to the sentences in between, correct? (I'm happy to add more, I'm just not sure how to do it well.)

[pkra]

I've added a manual note to the Braille project board https://github.com/w3c/aria/projects/9#card-40750290 so this is ready to merge.

[cookiecrook]

So the suggestion would be to add something to the sentences in between, correct? (I'm happy to add more, I'm just not sure how to do it well.)

Please go ahead and merge. We can always update later if a good idea presents itself. Thanks!

[cookiecrook]

Musing ideas for later... There could be tips on this in the APG... Things like, avoid capital letters and unnecessary punctuation in aria-brailleroledescription, because those burn one or more braille cells, defeating the purpose of terseness in this attribute.

[sinabahram]

True, but doesn't 8-dot settings for conveying caps take care of that particular concern? I want to be careful about content folks blanket-interpreting this to mean remove useful info and flatten Braille, which is totally not the intent, but may be an inadvertent result. Just something to keep in mind while coming up with these.