[Bug 23289] New: Suggested editorial fixes from EOWG

https://www.w3.org/Bugs/Public/show_bug.cgi?id=23289

            Bug ID: 23289
           Summary: Suggested editorial fixes from EOWG
           Product: HTML WG
           Version: unspecified
          Hardware: PC
               URL: http://www.w3.org/TR/2013/WD-html-longdesc-20130716/
                OS: All
            Status: NEW
          Keywords: editorial, LC
          Severity: normal
          Priority: P2
         Component: HTML Image Description Extension
          Assignee: mark@w3.org
          Reporter: mark@w3.org
        QA Contact: public-html-bugzilla@w3.org
                CC: public-html-admin@w3.org

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>

-- 
You are receiving this mail because:
You are the QA Contact for the bug.

Received on Thursday, 19 September 2013 14:06:12 UTC