Submitted on behalf of Shawn Henry/EOWG
http://lists.w3.org/Archives/Public/public-html-a11y/2013Sep/0037.html

Dear HTML Accessibility Task Force,

Thank you for the opportunity to review HTML5 Image Description Extension (longdesc)
W3C Last Call Working Draft 16 July 2013 <http://www.w3.org/TR/2013/WD-html-longdesc-20130716/>.

EOWG has several suggestions from an education and outreach perspective, below.

* Add "This section is non-normative." to main non-normative sections. (We see a sentence about this later, but are concerned it's not clear enough. For example, the first section under 3. The longdesc attribute <http://www.w3.org/TR/html-longdesc/#longdesc> starts with a sentence that is not clearly a "Note" (e.g., not offset, marked up, and preceded with "Note:"...")

* Introduction: Provide a little context at the beginning, briefly explaining what long descriptions are. For suggested wording, see the Image concepts page <http://www.w3.org/WAI/tutorials/images/> (note the lower sections have "Why is this important" and "How to make images accessible") and Complex images<http://www.w3.org/WAI/tutorials/images/complex>. Consider pointing to these pages for more information (although will need to check timing if it's still a draft and if Shadi & Bim are comfortable).

*Suggested edit to the paragraph under Use Cases and Requirements <http://www.w3.org/TR/html-longdesc/#UCnR>: "Text alternatives are required so that users can successfully understand and interact with images even if they cannot see, or see well. The alt attribute is designed to contain a short description. This is sufficient for most images, and should provide enough information to ensure that users understand the image's purpose. Some images contain more information than can effectively be provided in a short description. The longdesc attribute is designed for longer descriptions to meet use cases such as the following." — although, some of this information may be better in the Introduction per previous comment...

*Remove title from examples. (rationale: Using a title attribute in examples, even non-normative examples, could lead to proliferation of this technique via copy and paste. Use of title attributes is specifically ruled out in the 'HTML5: Techniques for providing useful text alternatives' draft <http://dev.w3.org/html5/alt-techniques/#secm7>.)

*Flow of Use Cases and Requirements: When reading the doc top to bottom, the "Requires:..." and "Helped by:..." under Use Cases do not make sense. It's only when you get to the next section that they make sense. Consider switching the sections around or explaining it.

*The items under "Requirements for an Image Description functionality" seem in random order. Is there a way to provide some structure or flow to them? (If there's nothing else, at least alphabetical order would help people reading the use cases and jumping down to the requirements to see the description of the things after Requires & Helped by.)

* Current wording: "This document does not define the term "accessible" nor accessibility, but uses them with the sense they have in [WCAG]" Change reference from WCAG to Introduction to Web Accessibility <http://www.w3.org/WAI/intro/accessibility> then can say more directly: "This document does not define the terms "accessible" or "accessibility"; it uses them as explained in Introduction to Web Accessibility.

* "Localizing" is not as well understood as "Translating"; therefore for the last use case, we suggest changing "Localizing" to "Translating". (also, could simply to "When content is translated to different languages"

* The Abstract says "Note that by allowing a hyperlink inside another one, this document explicitly redefines the HTML concept of hyperlink in a limited set of circumstances." Is this point clearly addressed in the main document? (Generally, the abstract is a summary and shouldn't have info that is not elsewhere.)

* copyediting:

- Suggest change "As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative." to "All authoring guidelines, diagrams, examples, notes, and sections marked non-normative in this specification are non-normative. Everything else in this specification is normative.

-Write out IDL on first reference.

-Quote terms as follows:
The key words "must", "should", and "may" in this specification are to be interpreted as described in [RFC2119].
This document does not define the terms "accessible" or "accessibility" (and change 'term' to "terms" and 'nor' to 'or'.)

-Use consistent capitalization in the headings.

- Under Use Case, last one has "it is important that metadata intended for human consumption". That seemed a bit awkward to some. Consider changing it to "it is important that metadata intended for people to read" or "it is important that metadata intended for humans" or such.

- "Authors should put descriptions within an element which is the target of a fragment link (e.g. longdesc="example.html#description") if a description is only part of the target document." is a bit hard to understand. Can you flip it around and say something like: "'When a description is only part of the target document, authors should include the [fragment link] in the element (e.g., longdesc="example.html#description")."

###

(Note: These comments do not necessarily represent consensus among all of EOWG, because not all participants were available to review the comments before we submitted them.)

Regards,
~Shawn Henry
for EOWG <http://www.w3.org/WAI/EO/EOWG-members.html>