Longdesc review

Comments from EOWG on HTML5 Image Description Extension (longdesc) W3C Last Call Working Draft of 16 July 2013

Note: EOWG review of technical documents should focus on understandability, approachability, and ease-of-use. Look especially at the introduction, background, use cases, and other such sections. Make sure the Overview page is linked early in the Introduction and in the Abstract, as appropriate. (If you have comments on technical aspects beyond the education & outreach perspective, please submit them yourself.)

Comments to submit

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 starts with a sentence that is not clearly a "Note" (e.g., not offset, marked up, and preceeded with "Note:"...")
Introduction: Provide a little context at the beginning, briefly explaining what long descriptions are. For suggested wording, see the Image concepts page (note the lower sections have "Why is this important" and "How to make images accessible") and Complex images. 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: "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.)
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.)
"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"
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 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.
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")."

Initial thoughts

EOWG minutes 13 Sept has discussion.

Introduction

[commented] Actual text: HTML 4 provided a longdesc attribute for the img element that enabled a machine-discoverable description of an image to be linked to the image.
Commment: from a user perspective, longdesc is not only for machines but to help people who cannot see or understand the image quite well, to know what it contains. Question: Is this sentence intent of the working group to focus only on technical issues or wouldn't it add argument to explain who benefits from longdesc if it is implemented and handled correctly? {Sylvie, 7 Sept}
The value of the longdesc attribute is not content for users, it is a pointer to the content for users, hence the attribute itself needs to be machine-discoverable to that browser UI and AT can provide a mechanism for accessing the description that longdesc points to. {ipouncey, 8 Sept}
[commented] 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) {ipouncey, 8 Sept}

Conformance

[consider bigger issue - beyond the scope of this document] I'd like to see "normative" and "non-normative" linked to a glossary definition. For a novice reader of these documents such of myself I really have no idea what these terms mean in this type of context. {Howard, 12 Sept.}
[commented] What does "IDL" mean? {Howard, 12 Sept.}
[commented] Current text: "The key words must, should, and may in this specification are to be interpreted as described in [RFC2119]..." I propose the following change: Add quotes for the keywords. The key words "must", "should", and "may" in this specification are to be interpreted as described in [RFC2119]. Rationale: it will make clearer which keywords are meant. {Sylvie, 7 Sept, 2013}
[commented] Current text: "This document does not define the term "accessible" nor accessibility, but uses them with the sense they have in [WCAG]". Proposed change: use term plural and use quotes for both accessible and accessibility. That would say: "This document does not define the terms "accessible" nor "accessibility", but uses them with the sense they have in [WCAG]".{Sylvie, 7 Sept, 2013}
I agree with the edit, but additionally 'nor' should become 'or' {ipouncey, 8 Sept}

Use Cases and Requirements

[commented] The leading paragraph to the use cases seems very confusing, terms like "everyday work" and "replaces an image" are unlikely to be clearly understood. Suggest changing the paragraph:
"There are many ways users can successfully interact with images even if they cannot see, or see well. The alt attribute is designed to ensure that for everyday work, a user has enough information to replace an image, and often this is more helpful than a detailed description of every image. The longdesc attribute is designed to complement this functionality, to meet the following use cases."

To:

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. Where an image contains more information than can be contained in a short description, the longdesc attribute is designed to complement this functionality, to meet the following use cases.

{Bim, 16 Sept.}
- Suggest changing "information to replace an image" with: "information to understand an image" - unless I'm not understanding the point of the sentence. {Howard, 12 Sept.}
Editors' reply: "Whether an image needs a long description can depend on context as well as the image itself. Alt is designed to provide a functional replacement text, not a short description. In many cases text alternatives are not necessary to support interaction. We therefore do not propose to adopt this edit." (from Dec 2013 email)
- @@[ideas for our reply:...] {name}
- I think EOWG's suggested edit was clearer. What about suggesting to modify the term that alt is the short description of the image.
  Proposed change: "The alt attribute is designed to contain a short text providing the function of the image or a short description of its content." {Sylvie, 10 January 2014}
- I’d add context to that sentence: “The alt attribute is designed to contain a short text providing the function of the image or a short description of its content, depending on the context of the image.” {Eric}
First sentence ends "images even if they cannot see, or see well " -- grammatically meaning that the images can't see well. Need to clarify it's the users. Anna Belle, 10 January 2014

closed comments:

[commented] The terms referred to in "requires" & "helped by" should anchor link to the glossary below. For a novice reader of these documents such of myself I really have no idea what these terms mean in this type of context. {Howard, 12 Sept.}

[commented] "Requirements for an Image Description functionality" - consider order (ABC?) or grouping or something to make easier to process.

[comments] I have no idea what is meant by: "Localizing descriptions: When content is localized to multiple languages, it is important that metadata intended for human consumption, such as image descriptions, can be readily localized." Mostly it's the word "localized" that's causing the most confusion. I don't like the term "human consumption" - it's too gastronomical. Seriously, I think something like "to provide information to the user" would work better.{Howard, 12 Sept.}

[commented] I would find the use cases easier to understand on the fist reading if the requirements were defined first, possibly prefixed with a sentence saying something like 'Use cases for longdesc have one or more of the following requirements.' {ipouncey, 8 Sept}

The longdesc Attribute

[OK as standards speak] "Zero or one" - this is confusing. Why not say: "One longdesc attributes may be added to any img element." {Howard, 12 Sept.}
[commented] This seems confusing: '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.' I understand this is an anchor link but I've never heard of a "fragment link." I'm not sure what this sentence is trying to say.{Howard, 12 Sept.}