{2 of 2] Fwd: Response to your comments on Accessible Rich Internet Applications (WAI-ARIA) 1.0

EOWG,

Below are replies to comments that we submitted on the WAI-ARIA document itself.

Let me know if you have further comments on these points.

~Shawn


-------- Original Message --------
Subject: Response to your comments on Accessible Rich Internet Applications (WAI-ARIA) 1.0
Date: Tue, 15 Dec 2009 00:34:12 +0000 (GMT)
From: Janina Sajka <janina@rednote.net>
Reply-To: PFWG Public Comments <public-pfwg-comments@w3.org>
To: Shawn Henry <shawn@w3.org>
CC: PFWG Public Comments <public-pfwg-comments@w3.org>


Dear Shawn Henry:



Thank you for your comments on the 24 February 2009 Last Call Working
Draft of Accessible Rich Internet Applications (WAI-ARIA) 1.0
(http://www.w3.org/TR/2009/WD-wai-aria-20090224/). The Protocols and
Formats Working Group has reviewed all comments received on the draft. We
would like to know whether we have understood your comments correctly and
whether you are satisfied with our resolutions.



Please review our resolutions for the following comments, and reply to us
by 1 February 2010 to say whether you accept them or to discuss additional
concerns you have with our response. You can respond in the following
ways:



* If you have a W3C account, we request that you respond online at
http://www.w3.org/WAI/PF/comments/acknowledge?document_version_id=1;



* Else, by email to public-pfwg-comments@w3.org (be sure to reference our
comment ID so we can track your response). Note that this list is publicly
archived.



Please see below for the text of comments that you submitted and our
resolutions to your comments. Each comment includes a link to the archived
copy of your original comment on
http://lists.w3.org/Archives/Public/public-pfwg-comments/, and may also
include links to the relevant changes in the Accessible Rich Internet
Applications (WAI-ARIA) 1.0 editors' draft at
http://www.w3.org/WAI/PF/aria/20091214/.



Due to the scope of changes made in response to comments on the Last Call
Working Draft of WAI-ARIA, we are returning the specification to Working
Draft status. We will shortly publish a public "stabilization draft" of
WAI-ARIA and updated Working Drafts of the accompanying documents. While
these versions will not incorporate further discussion based on your
acknowledgement of our response to your comments, we will work with you on
your feedback as part of our preparation for the following version. You are
also welcome to submit new comments on the new public versions in addition
to sending your acknowledgement of our response to your previous comments.



Note that if you still strongly disagree with our resolution on an issue,
you have the opportunity to file a formal objection (according to 3.3.2 of
the W3C Process, at
http://www.w3.org/2005/10/Process-20051014/policies.html#WGArchiveMinorityViews)
to public-pfwg-comments@w3.org. Formal objections will be reviewed during
the candidate recommendation transition meeting with the W3C Director,
unless we can come to agreement with you on a resolution in advance of the
meeting.



Thank you for your time reviewing and sending comments. Though we cannot
always do exactly what each commenter requests, all of the comments are
valuable to the development of Accessible Rich Internet Applications
(WAI-ARIA) 1.0.



Regards,



Janina Sajka, PFWG Chair

Michael Cooper, PFWG Staff Contact


Comment 79: Front-load content
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Comment: Make clear up front:

     * what is in that specific document and who it is for

     * that there are related documents designed for other audiences,

       &/or that are companions or dependencies of that doc

     * they should first have read the introduction to WAI-ARIA and the

       related documents at http://www.w3.org/WAI/intro/aria



   Editor Response: I think you were reviewing the editor's draft,

   which doesn't have the public Status of this Document section that,

   I believe, addresses this. I also feel the introduction section of

   each document covers this. Are there further edits we should make in

   service of this? If so, please send specific wording suggestions.



   EOWG Response: We think the first paragraph of the Introduction of

   each document should explicitly state what the document is, who it

   is for (and thus who it is not really for), that there are related

   documents that they might want to read first, and that they should

   read the WAI-ARIA Overview. For example, the Introduction in

   [2]http://www.w3.org/TR/wai-aria/ could start out something like:

   "WAI-ARIA is a technical specification that provides a framework to

   improve the accessibility and interoperability of web content and

   applications. This document is primarily for developers creating

   custom widgets and other web application components. Please see the

   [3]WAI-ARIA Overview for links to related documents for other

   audiences, such as the WAI-ARIA Primer that introduces developers to

   the accessibility problems that WAI-ARIA is intended to solve, the

   fundamental concepts, and the technical approach of WAI-ARIA."



      [2] http://www.w3.org/TR/wai-aria/

      [3] http://www.w3.org/WAI/intro/aria/



   We trust that Lisa Pappas can help with such wording for the other

   documents. :)



Additional comments on http://www.w3.org/TR/wai-aria/



   The spec's glossary says "Familiarity with W3C XHTML 1.1

   Recommendation [XHTML] and the W3C XML 1.0 Recommendation [XML] is

   highly recommended to understand..." Consider also if it would be

   useful to tell readers that up front (and then maybe not needed at

   the beginning of the glossary).

--------------------------------
Response from the Working Group:
--------------------------------
We have reorganized the introduction to better front-load the information,
and added your requested paragraph towards the top of this.

----------------------------------------------------------------------


Comment 80: Document title consistency
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Comment: For consistency with other WAI specs, consider the

   following titles/h1s:

     * Accessible Rich Internet Applications (WAI-ARIA) 1.0 [without

       ‘Version’]



   Editor Response: I made this change.



   Comment, continued: For consistency with other WAI specs, consider

   the following titles/h1s:

     * WAI-ARIA Primer for Accessible Rich Internet Applications 1.0

     * WAI-ARIA Best Practices for Accessible Rich Internet

       Applications 1.0

     * WAI-ARIA User Agent Implementation Guide for Accessible Rich

       Internet Applications 1.0

     * WAI-ARIA Roadmap for Accessible Rich Internet Applications 1.0

       [or no 1.0 needed?]



   Editor Response: I think this is super-awkward. This is kind of like

   saying "WAI-ARIA Best Practices for WAI-ARIA". I also don't see that

   this change would make it more consistent with other WAI specs. The

   other editors agreed that we don't want to make these title changes.



   EOWG Response: We would like to have a short title for easily

   referencing each document (as in the bullets at

   <http://www.w3.org/WAI/intro/aria#is>). We think it is best to have

   WAI-ARIA both as an acronym and spelled out in the title. Another

   option would be to use the acronym in the title, then write it out

   in a subtitle:

     * WAI-ARIA Primer: For Accessible Rich Internet Applications 1.0

     * WAI-ARIA Best Practices: For Accessible Rich Internet

       Applications 1.0

     * WAI-ARIA User Agent Implementation Guide: For Accessible Rich

       Internet Applications 1.0

     * WAI-ARIA Roadmap: For Accessible Rich Internet Applications 1.0

       [or no 1.0 needed?]



   This would be somewhat consistent with the naming scheme of the WCAG

   supporting docs:

     * Techniques for WCAG 2.0: Techniques and Failures for Web Content

       Accessibility Guidelines 2.0

     * Understanding WCAG 2.0: A guide to understanding and

       implementing Web Content Accessibility Guidelines 2.0

     * How to Meet WCAG 2.0: A customizable quick reference to Web

       Content Accessibility Guidelines 2.0 requirements (success

       criteria) and techniques



   NOTE: Please consider whether or not you need 1.0 in the short

   title, the subtitle, or neither.

--------------------------------
Response from the Working Group:
--------------------------------
We have agreed to retitle the documents as follows.



WAI-ARIA Authoring Practices 1.0: An author's guide to understanding and
implementing Accessible Rich Internet Applications

WAI-ARIA User Agent Implementation Guide 1.0: A user agent developer's
guide to understanding and implementing Accessible Rich Internet
Applications

WAI-ARIA Primer 1.0: An introduction to rich Internet application
accessibility challenges and solutions

WAI-ARIA Roadmap 1.0: W3C plans for addressing rich Internet application
accessibility gaps 

----------------------------------------------------------------------


Comment 81: Make normative clear
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   For documents that are informative (rather than normative

   standards/specs), make that clear.



   Editor Response: This is addressed in the status of this document

   (again, an editors draft issue).



   EOWG Reply: We think it needs to be more clearly stated in each

   document that the entire document is informative. For example, in

   both drafts of the Best Practices

   (http://www.w3.org/WAI/PF/aria-practices/ and

   http://www.w3.org/TR/wai-aria-practices/) it is at the beginning of

   some sections, but not in the introduction, main content sections,

   or status. (We assumed it will be published as a Note not a

   Recommendation, in which case the entire document is informative.)

   Be aware that readers are likely to skip the Status section

   (especially once the documents are published as final) and may miss

   it there.



Additional comments on http://www.w3.org/TR/wai-aria/



   The scopes of the statements "this section is normative" and "this

   section is informative" are not clear. Do they apply to the

   subsection or the whole "chapter"? For example, the "This section is

   informative." under 2 we assume means all of section 2. Under 5 is:



     5. Supported States and Properties

     This section is normative.

     5.1. Clarification of States versus Properties

     This section is informative.



   Maybe they should say: "Section 2 is informative" and "Section 5 is

   normative, except for subsection 5.1" ?

--------------------------------
Response from the Working Group:
--------------------------------
We will include a section in each document that explains the difference
between normative and informative, the interpretation of "This section is
normative" or "This section is informative", and remove references to
RFC2119 "normative" keywords from informative documents.

----------------------------------------------------------------------


Comment 82: Use WAI-ARIA
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Comment: <a>ARIA Overview</a> should be <a>WAI-ARIA Overview</a>



   Editor Response: I'm unclear if /all/ instances of ARIA should be

   presented as "WAI-ARIA". My personal preference is to do "WAI-ARIA"

   on first use in a section and plain "ARIA" after that. I believe

   you're requesting that all instances be the long form, but I'm not

   clear. It's actually easier just to find-replace it all to long form

   than to decide when to do long and when to do short, but I don't

   know if that's best for readability.



   EOWG Response: (Actually, we were just commenting on on the WAI-ARIA

   Overview link, but since you ask...)



   Per stated W3C usage (http://www.w3.org/WAI/aria/faq#justaria),

   please use "WAI-ARIA" in all headings at least.



   Additionally, EOWG suggests it is better to use WAI-ARIA on all

   references. While just ARIA uses fewer characters, it is a different

   word and thus takes extra processing the first time it is

   encountered. Most readers will process "WAI-ARIA" as a single entity

   anyway and the additional characters won't matter.

--------------------------------
Response from the Working Group:
--------------------------------
We have agreed to change all instances of "ARIA" to "WAI-ARIA".

----------------------------------------------------------------------


Comment 83: Explain terms and abbreviations
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Comment: Explain jargon like "user agent" on first use. Link terms

   to their definitions in the glossary. Make sure acronyms are written

   out in first use.



   Editor Response: I did a massive linking of terms, and wrapping

   <abbr> around everything I could think of, which I hope addresses

   this request. I actually think I may have overdone it, but it was

   with the expectation that it's easier to pull back than to go

   through another pass to add. I welcome feedback about the

   appropriate amount of term links and <abbr> markup.



   EOWG Reply: We recommend that acronyms are *written out* in first

   use, not just marked with <abbr>.



   We still think jargon needs to be explained in several places. For

   example, the first use of "user agent" could be written as:

   browsers, media players, and other "user agents" -- &/or linked to a

   definition. Perhaps Lisa Pappas can take a pass at this.



Additional comments on http://www.w3.org/TR/wai-aria/



   Additional words that need defining or explaining (&/or linking to a

   definition) on first use: role, state, attribute, taxonomy,

   ontology, landmark (as well as semantics).



   Currently "role, state and attribute" are used to explain

   "semantics"; however, some readers won't be familiar with those

   terms. Please define semantic without those terms as feasible.



   Note: Some people readers might miss the abstract. Therefore, if a

   term is defined in the abstract, it should also be defined on first

   use in the main document.

--------------------------------
Response from the Working Group:
--------------------------------
We will make the following edits to clarify definitions and abbreviations:



1) Add definitions for the terms "taxonomy", "ontology", "landmark", and
"semantics". (Note for definition of semantics from comment: Currently
"role, state and attribute" are used to explain "semantics"; however, some
readers won't be familiar with those terms. Please define semantic without
those terms as feasible.)



Landmark



A type of region on a page to which a user may want quick access. Content
in such a region meets a specific purpose, different from that of other
regions on the page and relevant to specific user purposes, such as
navigating, searching, perusing the primary content, etc.



Ontology



A description of the characteristics of [classes] and how they relate to
each other.



Semantics



The meaning of something as understood by a human, defined in a way that
computers can process a representation of an [object], such as [elements]
and [attributes], and reliably represent the object in a way that various
humans will achieve a mutually consistent understanding of the object.



Taxonomy



A hierarchical definition of how the characteristics of various [classes]
relate to each other, in which classes inherit the properties of ancestor
classes in the hierarchy. A taxonomy can comprise part of the formal
definition of an [ontology].



2) Make sure all terms that have a definition in the glossary link to that
definition.



3) For all abbreviations and definitions, synopsize their definition after
their first use in each major section.

----------------------------------------------------------------------


Comment 86: Separate informative content
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Alternate action taken

-------------
Your comment:
-------------
   Some EOWG participants suggest moving most informative information

   (especially the introductory info) to the supporting documents,

   because:

     * we are strongly encouraging readers to review the supporting

       documents before diving into the spec

     * the supporting documents (W3C Notes) can be updated more easily

       than the spec (Recommendation)

     * repeat users of the spec don't need the extra clutter of intro

       info



   Unlike many W3C specifications, WAI-ARIA comes with excellent

   supporting material in W3C Notes. EOWG recommends putting most

   informative information in the supporting documents, especially

   information that is likely to change over time. Look particularly at

   the use cases and examples.



   In order to help readers of the spec know what information they need

   to know to understand the spec, we suggest that the spec clearly

   point to what specific information certain readers should read --

   instead of only a single pointer to the intoductory document, since

   some readers will not need to wade through all of the supporting doc

   info. For example, something along the lines of:

     * [5]WAI-ARIA Overview provides a basic introduction and links to

       related documents.

     * [6]WAI-ARIA Primer describes to the accessibility problems that

       WAI-ARIA is intended to solve, the fundamental concepts behind

       WAI-ARIA, and the technical approach of WAI-ARIA. The following

       sections are particularly important for understanding this

       WAI-ARIA specification:

          + Use Cases

          + ...

     * [7]WAI-ARIA Best Practices provides detailed advice and examples

       directed primarily to Web application developers, yet also

       useful to user agent and assistive technology developers.



      [5] http://www.w3.org/WAI/intro/aria/

      [6] http://www.w3.org/WAI/EO/Drafts/comments/@@

      [7] http://www.w3.org/WAI/EO/Drafts/comments/@@

--------------------------------
Response from the Working Group:
--------------------------------
We believe the target audience for the WAI-ARIA documents will be more
inclined to dive in to the specification and best practices guide than to
link to the Overview and come back.



For this reason, we believe it is better to retain the information in the
WAI-ARIA documents while providing a reference to the Primer, for those
needing an introduction or context. We have modified the text in the
introduction scope to reference the Primer, Implementation Guide, and
Roadmap with text similar to what you have in the Overiew. We are moving
the section "Using WAI-ARIA" from the spec to the primer.

----------------------------------------------------------------------


Comment 87: Explain use cases more
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 - 1.2. Use Cases <http://www.w3.org/TR/2009/WD-wai-aria-20090224/#usecases>
Status: Alternate action taken

-------------
Your comment:
-------------
   [8]Section 1.2: Maybe an initial explanatory sentence would be

   appropriate here; e.g., saying how many use cases there are.



      [8] http://www.w3.org/TR/wai-aria/#usecases



   The first use case should be written as a need (as the second one

   is). Rather than "Keyboard accessible content helps users of

   alternate input devices" write "Users of alternate input devices

   need keyboard accessible content." The subject is "Users of

   alternate input devices" rather than "Keyboard accessible."



   Each of the two use cases is split into two paragraphs which is

   easier to read but harder to understand as the second paragraph is

   detached from its title ("Keyboard accessible" and "Assistive

   technology"). Perhaps there should be subheadings to group the four

   paragraphs into the two topics?

--------------------------------
Response from the Working Group:
--------------------------------
We have made the wording change you suggested for keyboard accessible.



However, the use cases section no longer exists as such, and some of the
content from that section has been incorporated into the overall
introductory material. Rather, the WAI-ARIA Primer explains uses cases for
ARIA. We have clarified in the introductory reference the Primer that it
contains use cases.

----------------------------------------------------------------------


Comment 88: Separate appendices
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 - 9. Appendices <http://www.w3.org/TR/2009/WD-wai-aria-20090224/#appendices>
Status: Accepted proposal

-------------
Your comment:
-------------
   Consider if the Appendices would be better on a separate HTML

   page(s).

--------------------------------
Response from the Working Group:
--------------------------------
We have agreed to move the appendices into separate pages.

----------------------------------------------------------------------


Comment 89: Pluralize 
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Use "assistive technologies"(plural) instead of "assistive

   technology"(singular) for consistency with other WAI documents.

--------------------------------
Response from the Working Group:
--------------------------------
We have made this change.

----------------------------------------------------------------------


Comment 90: Editorial
Date: 2009-04-15
Archived at: http://lists.w3.org/Archives/Public/public-pfwg-comments/2009AprJun/0061.html
Relates to: Accessible Rich Internet Applications (WAI-ARIA) 1.0 <http://www.w3.org/TR/2009/WD-wai-aria-20090224/>
Status: Accepted proposal

-------------
Your comment:
-------------
   Minor editorial notes:

     * "transform the presentation" sounds odd. "transform the

       presentation of content" might be better

     * "different ways than the author designed" might be better

       "different ways than the author intended"

--------------------------------
Response from the Working Group:
--------------------------------
We have made these changes.

Received on Tuesday, 15 December 2009 14:38:21 UTC