Note (***) indicates the comment is still open.
(Some additional information has been added to the responses based on EOWG's March 2008 review.)
Status: Send back to WAI-ARIA Editors
Comment: Make clear up front:
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 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 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."
We trust that Lisa Pappas can help with such wording for the other documents. :)
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).
Status: Send back to WAI-ARIA Editors
Comment: For consistency with other WAI specs, consider the following titles/h1s:
Editor Response: I made this change.
Comment, continued: For consistency with other WAI specs, consider the following titles/h1s:
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:
This would be somewhat consistent with the naming scheme of the WCAG supporting docs:
NOTE: Please consider whether or not you need 1.0 in the short title, the subtitle, or neither.
Status: Send back to WAI-ARIA Editors
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.
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" ?
Status: Send back to WAI-ARIA Editors
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.
Status: Send back to WAI-ARIA Editors
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 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.
Status: Probably Closed
Comment: Consider using the CSS as is in /TR/WCAG/, especially for the links to the definitions
Editor Response: We will take a look at this with a goal to adopting some of the styles from WCAG 2.0.
Status: Done
Comment: add [contents] link at the top, e.g., like /TR/WCAG/
Editor response: This is done.
Status: Done
Comment: Include link to public comments list in the Status section (or wherever else appropriate)
Editor Response: Standard for public status; editorial draft issue again.
Status: Done
Comment: In "This section is informative" link "informative" to definition and un-italicize.
Editor Response: Done. I linked normative and informative to a glossary entry. I used a "termref" class which is styled to look how older WCAG drafts did it. The style for that class may be updated in addressing the above CSS request.
Status: Done
Comment: Change "Semantics are knowledge of" to "Semantics is the knowledge of..."
Status: Send back to WAI-ARIA Editors
Comment: "Writing rich internet applications is much more difficult than writing in HTML. It is even more work to ensure your application runs in multiple browsers and supports WAI-ARIA." That is pretty strong. Please reconsider wording. This could be taken out of context and used to say that the main point is that ARIA is really hard, instead of how awesome it is to the user.
Editors Response: I'll happily take wording suggestions. I did nothing yet.
EOWG Response: Please reconsider the whole point of this section. Do you even need to say that it's hard? Also note that a library is not recommended in all cases; e.g., if you've just got one little slider you probably don't want to go through the whole deal to set up a library.
Maybe just say something along the lines of: "For complex applications, it is usually best to use existing widget libraries that implement WAI-ARIA and have already gone through:... [extensive assistive technology testing,
cross browser testing,
testing to ensure that the widgets respond to desktop settings,
testing to ensure that the widgets match a common keyboard style guide]"
Status: Send back to WAI-ARIA Editors
Comment: Note that some EOWG participants were somewhat uncomfortable telling people so strongly to use specific toolkits. (more on this is in a separate email)
Editor Response: We have agreed that we will make this change, but I can't promise when it will show up in a draft.
EOWG Response: Here is more specific suggestion, from the separate email. [This is in response to: "It is recommended that authors start by using a UI component library which has already implemented WAI-ARIA like the Dojo Toolkit Dijit library."]
While EOWG thinks it is useful to tell which toolkits implement WAI-ARIA, we are uncomfortable having the reference in a Note (or Recommendation) because of the time and effort required to update it. e.g., if another toolkit comes out with awesome WAI-ARIA support the day after this is published, it would not be listed for months or years until the Note is updated.
Please consider linking to a separate page where such information can be updated more easily -- perhaps in the FAQ <http://www.w3.org/WAI/aria/faq>. Also, please check if there are other references throughout the other documents that would be more appropriately handled on a separate page.
Some EOWG participants suggest moving most informative information (especially the introductory info) to the supporting documents, because:
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:
Section 1.2: Maybe an initial explanatory sentence would be appropriate here; e.g., saying how many use cases there are.
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?
Consider if the Appendices would be better on a separate HTML page(s).
Use "assistive technologies"(plural) instead of "assistive technology"(singular) for consistency with other WAI documents.
Minor editorial notes:
###