Re: authoring guidelines in aria-keyshortcuts

> On Apr 14, 2016, at 8:03 PM, Matt King <a11ythinker@gmail.com> wrote:
> 
> Rich, I think we will just have to talk about this in the meeting. It doesn’t seem like you are understanding my points.
>  
> In the mean time, here is an alternative proposal. Instead of restrictive normative language, how about something like:
>  
> Note: It is important to design a keyboard interface that does not inhibit usability of assistive tehcnologies, the user agent, or operating system environment. See section XX of the APG for guidance.
>  
> I will commit to drafting a section for the APG before CR. That way we can give actionable guidance as well as address trickier decisions like making a decision about conflicting with user agent keys like those for save and print, for example.
Matt, 

We want to have ARIA locked down in June. I need to see an acceptable section of text pertaining to that attribute, in the APG, before them if I am going to take anything out. The working group needs to agree on the text. 

Also, just because I don’t agree with you does not mean that I don’t understand you. 

It must deal with AT conflicts
It must deal with browser and OS conflicts. 
It must address the issues with different keyboard layouts if you want any of that text moved over. It does not have to be exhaustive. 

>  
> If it helps, here are some thoughts on the points you raised.
>  
> Rich wrote:
> >Well, James Craig who’s team works on VoiceOver believes differently. 
> >Yes, it is the onus on the site owner. 
> >How is an AT vendor going to test with every possible site that is out there?
>  
> AT vendors do not have to do that. A real-life example scenario, the likes of which has  occurred many times, is something like this:
> ·         Microsoft Excel on the web adds a feature that uses alt+shift+c. The designers consider this a logical assignment because it is consistent with the desktop version and it fits into a well-defined keyboard scheme.
> ·         A popular screen reader that Microsoft intends to support also adds an Excel support feature that uses alt+shift+c, say specifying which cell to treat as a column title.
> ·         Screen reader users bring the conflict to the attention of the screen reader developer.
>  
> Today, the screen reader developer would treat this as a screen reader bug. The key assignment would have been recognized as a poor choice because the key is for a screen reader function but the assignment didn’t include the screen-reader-specific key modifier, e.g., insert or capslock. The screen reader developer could resolve it by changing it to insert+shift+c or insert+ctrl+c or something else that included the screen reader modifier. This type of scenario happens often as the number of screen reader key assignments continues to balloon toward infinity and finding logical assignments that include the screen reader modifier gets more difficult. 
>  

Matt, you cannot compare the Web with software application in this space. There are a finite number of key software applications that they support. 

Also, you of all people should know how hard it is to get an AT to customize their UI for a single app. and doing so for 1 out of a billion web sites is insane. 

> With this spec language, screen reader developers or users could legitimately argue that Microsoft should have to change its key assignment even if Microsoft’s design cycle was done before the screen reader feature was added.
>  
> Rich wrote:
> >It is highly unlikely that a developer is going to get an AT vendor to change their key assignments 
> >over a key conflict on a single site.  
>  
> That would depend on the specific circumstances. Often, though, it will be the AT users that will drive the change in a way similar to what I described above. In either case, is it the goal of the ARIA spec to be the arbetor in such UX design discussions?
>  
> Rich wrote:
> >I don’t recall WCAG having success criteria about keyboard assignments for ATs. 
>  
> WCAG has keyboard guidance for authors. That is what we are discussing. However, I just looked at SC 2.1, and I don’t see anything about conflicts. I think I was recalling something from 508.
>  
> >There is nothing we would be required to test for an author SHOULD. 
> >It is there to make sure the author does not step in it 
> >if they are going to implement a keyboard shortcut and document it through ARIA.
>  
> But, my very first point is that this is not necessarily something authors should always avoid.
>  
Rather than guessing, Let me see the text you want to put in the APG. 

> Matt wrote:
> >If I were a designer or a developer working on 
> >ensuring compatibility with a narrowly defined set of assistive tehcnologies and platforms, 
> >and if I were working on my keyboard design, 
> >wouldn’t studying how to accommodate potential conflicts or testing for adverse effects related to them 
> >be an obvious course of action? 
> >Even if you know almost nothing about accessibility 
> >and you have the intention of supporting VoiceOver on the Mac in Safari, 
> >then step one will be to turn on VoiceOver in Safari. 
>  
Not for many people - no. The people in our group are not normal people Matt. We know much more than the average developer or designer about these issues. 

> Rich wrote:
> >it may be obvious to you and me because we have worked in the industry a long time. 
> >It is not for the average developer. 
> >I remember your spending a lot of time working with the Connections team teaching them how a screen reader worked at all 
> >and how to test with it. 
> >This is the discussion I had with you about being a 25 year power user. 
>  
> Rich, I was talking about a beginner. Look at the starting set of assumption that you provided:
> 1.      The author intends to support a specific assistive technology.
> 2.      The author is designing for a specific platform.
>  
> I am assuming 2 pieces of knowledge about the accessibility requirements: the author knows which assistive technology and which platform they plan to support. And, because you mentioned designers and developers, I am assuming the author is a UX designer or web developer. Finally, the task assigned to this designer or developer is design a keyboard experience for a web app that must support the given assistive technology and run on the given platform.
>  
> If the author knows nothing about the assistive technology and was given this assignment, what would the author do? Wouldn’t one of the first things such an author might do be to play with or study the assistive technology?
>  
> Having trained 100s or maybe thousands of people who are accessibility noobs, I have a good signal on my ability to meet people at their specific level. I am confident in the assumption I have made above. I am also confident that the sweeping statements about avoiding key conflicts are too broad to be helpful or actionable. But my bigger concern is that they might lead people astray or cause unnecessary churn.
>  
You can’t claim to be the only person in the group to do this. Let us see what you want to propose in the authoring practices. Again, I want to lock this down by June. So, I can assure you that given the results of what has been coming out of the IBM design groups that much of this is not addressed at all. We are now having to go back in and fix it. 

At his point, I think the text should go in as is subject to something concrete in the APG prior to a June lock down that is acceptable to the group. 

Rich


> Matt
>  
> From: Rich Schwerdtfeger [mailto:richschwer@gmail.com] 
> Sent: Thursday, April 14, 2016 3:13 PM
> To: Matt King <a11ythinker@gmail.com>
> Cc: ARIA <public-aria@w3.org>
> Subject: Re: authoring guidelines in aria-keyshortcuts
>  
>  
> Rich Schwerdtfeger
>  
>  
> 
>  
>> On Apr 14, 2016, at 4:46 PM, Matt King <a11ythinker@gmail.com <mailto:a11ythinker@gmail.com>> wrote:
>>  
>> Rich,
>>  
>> The feeling I have when I read your response is that I did not state my concerns clearly. Perhaps I expressed concerns with too many different statements in one note.
>>  
>> I’ll try clarifying by focusing on just this one point, where you wrote:
>> > That is why it is worded the way it is: 
>> >"Authors SHOULD avoid keyboard shortcuts that are used by supported assistive technologies 
>> >running on the intended operating system platforms.”
>>  
>> I don’t think the aria-keyshortcuts description should include that statement. Here are my reasons. I will explain them below. 
>>  
>> 1.      Authors do not necessarily need to avoid this type of conflict to create an accessible experience.
>> 2.      If an assistive technology conflict does arise, it appears to put the onus on the web site owner and gives the assistive technology developer a free pass.
>> 3.      If “supported” and “intended” refer to the author’s efforts and intentions, it is a non-statement. It is like telling the author, “If you intend to draw a circle, do not draw a square.”
>> It seems to be that normative author statements in the spec should be limited to telling authors how to correctly use the property. In this case, that means documenting the requirements for representing key assignments in the string token in a way that will result in accurate representation of that key shortcut in accessibility APIs. You should be able to meet those requirements regardless of whether the key assignment is a good one or a bad one from a UX design perspective.
>>  
>> Here are my explanations.
>>  
>> Point 1:
>> Authors do not necessarily need to avoid this type of conflict to create an accessible experience.
>>  
>> There are at least 2 circumstances where direct conflicts with assistive technology key assignments are a non issue. 
>>  
> Well, James Craig who’s team works on VoiceOver believes differently. Yes, it is the onus on the site owner. How is an AT vendor going to test with every possible site that is out there? Sorry, but I don’t follow your logic at all. 
> 
> 
>> First, in an attempt to provide enhanced user experiences in popular applications, some assistive tehcnologies intentionally intercept shortcuts that are used by applications in order to modify the experience associated with the application function that is executed by that shortcut. In this case, it is essential that the the assistive technology and the application have the same key assignment for a given set of intentions, even if the set of intentions supported by the assistive technology are broader or narrower than those of the application author.
>>  
>> Second, an application author may provide a key assignment that does not work for assistive technology users but also provide an additional assignment that does. For example, people who are not using assistive technologies may be able to press a letter key to execute a function, e.g., “R” to reply. But, if the reply function is available in a document context, the author may also support alt+r and op-R so that screen reader users can access the reply function without leaving document browse mode. In this case, the author has not avoided the conflict but has instead provided alternative keys.
>>  
> That is why it is a SHOULD and not a MUST. However, to make that determination they would need to test with the AT to address the conflict. 
> 
> 
>> There may be a third circumstance. An example of this does not immediately come to mind, but there may be scenarios where a keyshortcut is assigned to a function that is not useful for users accessing the page with certain types of assistive technologies.
>>  
>> Point 2: 
>> If an assistive technology conflict does arise, it appears to put the onus on the web site owner and gives the assistive technology developer a free pass.
>>  
>> With the thousands of key assignments that are sucked up by assistive technologies, there are times where assistive technologies step into territory that really does not belong to them. While there are no formal boundaries, most assistive tehcnologies have a set of conventions that are designed to avoid conflicts. But, occasionally, especially when attempting to provide support for specific applications, AT developers have difficulty finding workable keyboard schemes and stretch their conventions. This has happened multiple times over the years and when a conflict with a popular application arises, it is often more appropriate for the AT to change than the application. With this language in the spec, I can imagine some people attempting to force changes on an application owner when it would be better for the AT to make the change.
>>  
>  
> See my point above. It is highly unlikely that a developer is going to get an AT vendor to change their key assignments over a key conflict on a single site.  
>  
> 
> 
>> Because there is no simple way for page authors to build a list of all active key assignments for an assistive technology they wish to support, users will typically be the people who find these conflicts. This particular problem is becoming more prevalent on the web as assistive technologies are more often providing customization that apply only to specific web sites and apps.
>>  
>> Point 3: 
>> If “supported” and “intended” refer to the author’s efforts and intentions, it is a non-statement. It is like telling the author, “If you intend to draw a circle, do not draw a square.”
>>  
>> If I were a designer or a developer working on ensuring compatibility with a narrowly defined set of assistive tehcnologies and platforms, and if I were working on my keyboard design, wouldn’t studying how to accommodate potential conflicts or testing for adverse effects related to them be an obvious course of action? Even if you know almost nothing about accessibility and you have the intention of supporting VoiceOver on the Mac in Safari, then step one will be to turn on VoiceOver in Safari. Step 2 will be learning the basics of operation, and by that point in time, it is obvious that you must use a keyboard to operate VoiceOver. If you were designing or coding the keyboard experience, you would not need to be told to avoid assigning an application function to ctrl-opt-RightArrow.
>>  
>  
> Matt, it may be obvious to you and me because we have worked in the industry a long time. It is not for the average developer. I remember your spending a lot of time working with the Connections team teaching them how a screen reader worked at all and how to test with it. This is the discussion I had with you about being a 25 year power user. 
> 
> 
>> Point 4:
>> Author guidance in the spec should focus on telling authors how to correctly use the property. In this case, that means documenting the requirements for representing key assignments in the string token in a way that will result in accurate representation of that key shortcut in accessibility APIs. You should be able to meet those requirements regardless of whether the key assignment is a good one or a bad one from a UX perspective.
>>  
>> If the key assignment for a function is alt+r, authors need to know if they can write aria-keyshortcuts=”ALT+R” or aria-keyshortcuts=”alt-r” or aria-keyshortcuts=”opt-r” or … They need to know what the requirements for the value token are. If they know that, they can effectively use the property to document key shortcuts for any web page. The aria-keyshortcuts property will work effectively regardless of whether the author made really bad or really good choices for the key assignments. 
>>  
>> There is a nearly boundless supply of UX issues closely related to many ARIA roles, states, and properties and we have a robust set of related standards and documents that attempt to address them. As I look at the normative authoring statements in other roles, states, and properties, they appear to be addressing requirements that are essential to ensuring the role, state, or property is properly represented in accessibility APIs and ensuring that the accessibility tree that sits behind that API is well-formed, e.g., required owned elements are present. The closest that normative author statements come to UX design in most roles is a generic statement about managing focus.
>>  
>> The more we put into the spec about UX design, the less extensible the standard becomes.
>>  
>> An alternative approach could be to add a note that references relevant WCAG requirements or success criteria.
>>  
>> Those are my concerns with the first of the 3 authoring statements about keyboard conflicts in the aria-keyshortcuts property. I have similar but not identical concerns with normative authoring statements about key conflicts related to user agents and operating systems.
>>  
> It is a SHOULD and not a MUST. I don’t recall WCAG having success criteria about keyboard assignments for ATs. There is nothing we would be required to test for an author SHOULD. It is there to make sure the author does not step in it if they are going to implement a keyboard shortcut and document it through ARIA.
>  
> Note: WCAG has a tendency to be years behind the ARIA specs. 
>  
> 
> 
>> Matt
>>  
>> From: Rich Schwerdtfeger [mailto:richschwer@gmail.com <mailto:richschwer@gmail.com>] 
>> Sent: Friday, April 8, 2016 6:35 AM
>> To: Matt King <a11ythinker@gmail.com <mailto:a11ythinker@gmail.com>>
>> Cc: ARIA <public-aria@w3.org <mailto:public-aria@w3.org>>
>> Subject: Re: authoring guidelines in aria-keyshortcuts
>>  
>> Matt, 
>>  
>> 1. I agree. That is why it is worded the way it is: "Authors SHOULD avoid keyboard shortcuts that are used by supported assistive technologies running on the intended operating system platforms.”
>>  
>> “intended” operating systems and “supported” assistive technologies is in there for a reason. If you are writing a web application you need to test with an assistive technology. Those that you support on the targeted operating system should be what the author should be directed to do. We cannot expect the author to support everything on the planet. 
>>  
>> 2. I agree. That is why it is written as a SHOULD and not a MUST. It is worded as:
>>  
>> "Authors SHOULD avoid using keyboard shortcuts that are used by the user agent. Implementing keyboard shortcuts that conflict with the user agent, will result in a loss of user agent functionality.”
>>  
>> 3. Here we disagree. Every operating system has its own set of keys that are stolen. If the author is writing a web page and does not test for each OS platform they are targeting that is a problem. Sometimes people test on only one platform. 
>>  
>> Many designers look at the ARIA specs. In fact when they don’t think about the page semantically we get accessibility added late in the process further driving up costs. UX designers at IBM have started provided  keyboard implementations in their designs. I just saw this from the Verse design team this past week based on the discussion with the CSS Working Group at CSUN regarding Flexbox. The author is required to implement what the designer asked and this is a vehicle for exposing the documentation to the user. We are looking at creating new tools for designers to make this easier for them to expose the keyboard design to developers. 
>>  
>> Sorry, but you have not made a compelling argument and Apple has also provided feedback that these issues needed to be addressed. 
>>  
>> If you do not plan on addressing these issues then I definitely don’t want this guidance in the design guide. So, before I agree you need to show me a section of the authoring practices guide that includes guidance like this. Otherwise, I do not support taking it out. 
>>  
>> Also, if we want to make more references to the Authoring Practices we need a standard way of doing that in the ARIA spec. My concern is that the authoring practices is not a normative document. It is more of a living document where content changes. We can’t have broken links in a normative spec. Also, moving all the authoring guidance this late in ARIA 1.1’s development is a concern. I would rather consider that for an ARIA 1.2. … IOW I like the idea but we would need to do this throughout the document to put this in a normal flow for developers and designers. Neither the HTML or SVG specs. do this today. We would be a first to do it. We also need to address necessary RFC SHOULDs and MUSTS for an authoring guide. 
>>  
>>  
>>  
>> Rich
>>  
>> Rich Schwerdtfeger
>>  
>>  
>> 
>>  
>>> On Apr 7, 2016, at 7:26 PM, Matt King <a11ythinker@gmail.com <mailto:a11ythinker@gmail.com>> wrote:
>>>  
>>> Hi Rich,
>>>  
>>> The reason I am pushing back on these statements about key conflicts is because I think the guidance statements, as written, are not helpful and may in fact cause confusion or lead authors astray. I do not believe it is useful to make a blanket statement that tells authors they SHOULD avoid key conflicts with all screen reader keys, all user agent keys, and all operating system keys. 
>>>  
>>> 1.      Screen reader keys: it is almost impossible to conflict with them in the first place because of the way screen readers are designed.
>>> 2.      User agent keys: conflicting with them is often a necessary part of creating a good UX and rarely blocks access to or even inhibits convenient access to UA functionality. Of course, authors SHOULD avoid blocking UA functionality. This is a topic that should be addressed in the APG; it can’t be done in a sentence.
>>> 3.      Operating system keys, you can’t conflict with them in a web app so why bother mentioning it.
>>>  
>>> The other issue is that the keyshortcuts property is only a documenting mechanism, not an implementation mechanism. So, it is hard to imagine anyone turning to that part of the spec for UX design guidance. 
>>>  
>>> However, If there is consensus that the spec must include guidance on this topic, then I’d like to suggest we reword it in a way that is efficacious. I’d be happy to suggest some wording if there is consensus that the ARIA spec should include UX design.
>>>  
>>> That said, I’d like to reemphasize the idea that we should have a reasonably high bar for inclusion of authoring guidance in the spec. I would like to propose that the spec should only include authoring guidance that is essential to effective implementation of an ARIA role, state, or property and that such guidance be included in the description of that role, state, or property. In this case, you can effectively implement the keyshortcuts property no matter what silly key assignments someone may make. Guidance on which keys to implement is an UX design topic that generally only intersects with ARIA in the implementation of widgets. And, for that aspect, it is all non-normative and and deligated to the APG.
>>>  
>>> It is probably better that authors use the keyshortcuts property to reveal their design, no matter how crummy, rather than leave users in the dark.
>>>  
>>> Matt
>>>  
>>> From: Rich Schwerdtfeger [mailto:richschwer@gmail.com <mailto:richschwer@gmail.com>] 
>>> Sent: Thursday, April 7, 2016 3:49 PM
>>> To: ARIA <public-aria@w3.org <mailto:public-aria@w3.org>>; Matt King <mck@fb.com <mailto:mck@fb.com>>
>>> Subject: authoring guidelines in aria-keyshortcuts
>>>  
>>> For some reason my Mac mail was copying messages into my other personal mail folder vs. gmail and made a mess of things. I ended up cleaning up my personal email box so I don’t have a copy of your email about putting all the authoring guidance in the authoring practices. 
>>>  
>>> I principle I agree with this, however for some general guidance that I think is critical like remembering to think about the browser, platform AT, and OS and I can’t reference the authoring practices from the spec. at this time as I can’t really reference key shortcut guidance in the authoring practices document now and your list of to-dos is already extensive. So for now I would like to keep that guidance in here. If you create a section of the authoring practices that includes these points and all the other possible keyboard specific issues (it is comprehensive) we can reference that in the future. 
>>>  
>>> We agree this is definitely an authoring issue. There is precedence in the ARIA spec. to include authoring guidance in a number of places. 
>>>  
>>> Rich
>>> Rich Schwerdtfeger