Review new Read Me First section

[mcking65]

A proposed draft of a new
Read Me First
section is ready for review. This addresses issue #474, and adds statements regarding browser and assistive technology support and mobile/touch compatibility.

Task Force Reviews Requested as of October 15, 2017

• Review by Ann (@annabbott)
• Review by Bryan (@accdc)
• Review by James (@jnurthen)

[devarshipant]

Consider - http://w3c.github.io/aria-practices/#no_aria_better_bad_aria and the para "Using a role without fulfilling the promise of that role is similar to making a "Place Order" button that abandons an order and empties the shopping cart."

I think the analogy will be more easily understood when the example code <div role="button">Press Me</div> reflects some part of the analogy.

[mcking65]

@devarshipant, could that be achieved with a change as simple as changing:

<div role="button">Press Me</div>

To:

<div role="button">Place Order</div>

Or, did you have something else in mind?

[devarshipant]

Yes, that change connects the two pieces. Thank you!

[annabbott]

Reviewed and found no changes needed, aside from the one mentioned by @devarshipant .

[devarshipant]

A few suggestions:

• Under Principal 2 (http://w3c.github.io/aria-practices/#no_aria_better_bad_aria)

1. Code example - <a aria-label="Assistive tech users perceive this aria-label, not the link text">Link Text</a> should be:
   <a aria-label="Assistive tech users perceive this as a label, not the link text">Link Text</a>

2. Users could get overwhelmed trying to seek more information sorrounding ARIA, APIs, etc. on their own. I think there should be references (or helpful bits in this section) to understand where and how ARIA fits in the grand scheme of things by mentioning or referencing:

• Relationship between DOM, Accessibility Tree, and Accessible Object (https://www.w3.org/TR/core-aam-1.1/#intro_treetypes)
• It’s relationship with accessibility APIs (https://www.w3.org/TR/core-aam-1.1/#accessible-names-and-descriptions)
• General rules of exposing ARIA semantics (https://www.w3.org/TR/core-aam-1.1/#mapping_general)
• Role mapping and how Assistive Technology interprets the table at https://www.w3.org/TR/core-aam-1.1/#mapping_role_table

[accdc]

This section looks good to me, though I'd recommend changing the following:

"Functionally, ARIA roles, states, and properties are sort of like CSS for assistive technologies."

To the following instead:

"Functionally, ARIA roles, states, and properties are analogous to CSS for assistive technologies."

[LaurenceRLewis]

Although the word analogous is perfectly suited — I believe many users won’t understand or relate to it. Therefore I recommend changing to: “...properties are comparable with css ...”

[mcking65]

@devarshipant commented:

<a aria-label="Assistive tech users perceive this aria-label, not the link text">Link Text</a>

should be:

 <a aria-label="Assistive tech users perceive this as a label, not the link text">Link Text</a>

Kind of ... it is not just that aria-label is a label, but that it is the only thing that is perceivable because it wipes out acccess to the link text. I made a change in commit 0ef198f that hopefully makes that more clear.

Users could get overwhelmed trying to seek more information sorrounding ARIA, APIs, etc. on their own. I think there should be references (or helpful bits in this section) to understand where and how ARIA fits in the grand scheme of things by mentioning or referencing:
Relationship between DOM, Accessibility Tree, and Accessible Object ( https://www.w3.org/TR/core-aam-1.1/#intro_treetypes)
It’s relationship with accessibility APIs ( https://www.w3.org/TR/core-aam-1.1/#accessible-names-and-descriptions)
General rules of exposing ARIA semantics ( https://www.w3.org/TR/core-aam-1.1/#mapping_general)
Role mapping and how Assistive Technology interprets the table at https://www.w3.org/TR/core-aam-1.1/#mapping_role_table

We could definitely help people navigate the documents that serve as the basis for the practices. And, with issue #84, we plan to add an appendix on the background of ARIA. These kind of references could be part of that or in another appendix related to it.

this section is intentially void of links to avoid rabbit holes that might distract people from reading all the way through. My hope is to give people the bare-bones, not-so-obvious, information needed to use the guide successfully.

[mcking65]

Thank you @accdc and @Decrepidos for the feedback.

I like the suggestion to explicitly state that I am making an analogy between CSS and ARIA. And, I modified the following sentence to strengthen the meaning in the event that the first sentence is not well comprehended.

Changes made in commit 0ef198f.

[mcking65]

Thank you all for the feedback. Marking this as complete.