Comments on 8 December AUGL

Hello,

I reviewed the 8 December AUGL although I realize there has been
at least one draft since then. However, I don't think any of my
edits concern what has been added (I need to verify).

Please note that while this email is somewhat long, my comments
are mostly proposals for editorial clarification (including
clarification
of text in several checkpoints). I think Issue 1 is the only exception, 
and that involves coordination with the UA Guidelines.

Issue 1) Section 1.3 (Conformance to these Guidelines).
 
  Form 1 describes what information must be made available in a detailed
  conformance claim (AUGL version, conformance level, checklist, etc.).
  In the UA WG, we have been discussing ways to deliver this information
  (this was discussed at the 10 December UAGL face-to-face in Austin as
issue
  136).  would like the methods used by the AU Guidelines and UA
Guidelines
  to be the same, even if details of the claim vary slightly. 

  Proposed: In Form 1, explain that the information required for the
  claim (the bulleted list) may be provided in the software
documentation or
  on the Web. In the latter case, the claim would be accompanied by a
URI to
  the claim information on the Web.

  [1] http://cmos-eng.rehab.uiuc.edu/ua-issues/issues-linear.html#136

Issue 2) Editorial change to checkpoint 2.2: change "inform" to "alert".

   Old text: "If markup generated by the tool does not conform to W3C
   specifications, inform the author."

   The term "alert" is well-defined, while "inform" is not. The term
  "alert" is defined as "draw the author's attention to an 
   event or situation." Invalid markup is a situation.

Issue 3) Checkpoint 3.3
  a) In the Note, it is not clear that "movies" are movies that come
     with the tool. I propose adding the word "prepackaged" before
"movies".
  b) Make "auditory descriptions" plural in the Note.

Issue 4) Checkpoint 3.4: Both the checkpoint and note are unclear to me.
  Old text: "Do not insert automatically generated or place-holder
            equivalent alternatives."

  a) The term "automatically" is redundant since "generate" in this
     document means the tool created the content on its own.

  b) "place-holder" is not clear to me and is not explained in the
     Techniques document. I don't think it's necessary because either:
         1) The tool generated the place-holder and therefore it's
            subsumed by "don't generate equivalent alternatives", or
         2) The tool is reusing a previously authored equivalent. In
            this case, the requirement may be "Don't reuse
            previously authored equivalents without confirmation 
            from the author."

  c) The first example in the checkpoint note is unclear 
     and should be deleted.

  Proposed new checkpoint text and note:

    Checkpoint 3.4 Do not generate equivalent alternatives. Do not reuse
                   previously authored alternatives without author
confirmation.

     Note: For example, prompt the user for a text equivalent of an
image. If
           the author has already provided a text equivalent for 
           the same image used in another document, offer to reuse that
           equivalent and prompt the author for confirmation. Refer also
to
           checkpoints 3.3 and 3.5.

Issue 5) Proposed edit to checkpoint 3.5

   Old text: Provide a mechanism to manage alternative information for
             multimedia objects, that retains and offers for editing 
             pre-written or previously linked equivalent
             alternative information.

   New text: Allow the author to manage, edit, and reuse alternative
             equivalents for multimedia objects. 
  
       Note: These alternative equivalents may be packaged with the
             tool, written by the author, retrieved from the Web, etc.

Issue 6) Checkpoint 4.5
 
   Old text: "Allow the author to transform presentation markup that is
              misused to convey structure into structural markup, 
              and to transform presentation
              markup that is stylistic into style sheets."

  I don't understand "presentation markup that is stylistic". 
  Isn't that what "presentation markup" means? I propose dropping 
  "that is stylistic".

Issue 7) Checkpoint 5.1

   Old text: "Ensure that functions relatd to accessible authoring
              practices are naturally integrated into the tool."

   a) I think "features" or "functionalities" would be better than
     "functions".
   
   New text: "Ensure that features related to accessible authoring
             practices are naturally integrated into the tool."

   (Ian Note: I am tempted to suggest "into the user interface" as a
    more specific substitute for "into the tool." But I think I'll 
    be shot down.)

Issue 8) Guideline 7 rationale question:

   Old text: "When custom interface components are created it is
              essential that they are accessible through 
              standard access mechanisms."

   What are "standard access mechanisms?" How do they apply to custom
   controls?

Issue 9) The note after checkpoint 7.2 should be deleted.

  Text about being able to author with one style and publish with
  another appears three times:

   a) Paragraph 2 of Guideline 7 rationale
   b) Checkpoint 7.2
   c) The note after 7.2 (which offers little more information than the
      checkpoint.

  Proposed: Delete the note after 7.2

OTHER EDITORIAL COMMENTS and SUGGESTIONS

Edit 1) Text about accessibility of content and acessibility of the UI
        appears at least four times in the document:

  a) First sentence of the abstract
  b) First sentence of the introduction
  c) First sentence after the bulleted list of the introduction
  d) First sentence of the paragraph after that (which is the third
     paragraph)

  I propose deleting two instances as follows:

  a) Abstract: no change.

  b) Delete the first sentence of the Introduction. [NOTE: If the first
     sentence is, for some reason, not deleted, change the first
instance of
    "designed to help" to "explain to authoring tool developers 
    what must be done to.."

  c) Delete the first sentence of the third paragraph. Edit the second
     sentence to read: "To achieve these goals, authoring tool
     developers must ensure conformance to accessible standards ..." 

Edit 2) Paragraph three of Introduction: change "rather than directly
        reproduce" to "rather than reproducing".


Edit 3) Do a global replace: capitalize "Techniques Document"

Edit 4) In the last bullet of second list of 1.1, before
[WAI-AUTOOLS-TECHS],
        write "the Techniques Document".

Edit 5) In the definition of Relative Priority, after the first instance
        of Web Content Accessibility Guidelines, include the acronym
WCAG
        (with appropriate HTML markup as well). 

       Still in the relative prirority definition, put commas around
"without it"
       in the first example.

       in the paragraph after the example, change "Web Content
Guideline" to
       WCAG

Edit 6) In checkpoint 2.1, put a comma after "where possible".

Edit 7) In Guideline 3 sentence one, hyphenate "well-structured" and
remove
        comma from after "information".

Edit 8) In Guideline 4 rationale, paragraph two change "help authors to
feel"
        to "help authors feel".

Edit 9) In Guideline 5 rationale, change "different ways to achieve the
same thing"
        to "different ways to accomplish the same task".

Edit 10) In the definition of "Alternative Information", put "WCAG"
before 
       [WAI-WEBCONTENT].

Edit 11) In the definition of Attribute, delete the markup 
         example and move it to the Techniques. It doesn't explain
anything
         as is.

Edit 12) In the definition of Auditory Description, start the second
sentence
         with "Auditory descriptions" instead of "They".

Edit 13) Change definition of "Conversion tool" to:

         "A conversion tool is any application or application feature 
          (e.g., "Save as HTML") that  transforms
          convent in one format to another, and in particular
          a markup language."

Edit 14) There's a source document bug in the definition of "Check for".
         Also, "guess" needs a space afterwards and "linearided" is
misspelled.

Edit 15) Delete the second sentence of "Editing view" since it's about
         views in general, not just editing views. Possibly moved with
edits
         to the definition of View.

Edit 16) In "Markup Language", change "HTML" to "HTML 4.0". 

Edit 17) In the definition of "Prompt", remove the reference to
"alt-text"
         since that term is never defined. Instead, edit to refer to
         text equivalents.

Edit 18) In the definition of Property, change "the name of the element"
         to "the type of the element". Also, change the last word of the
         definition from "element" to "entry" since it's talking about
         databases.

Edit 19) There are two missing glossary headers in the Guidelines:
         "Rendered Content" (mistakenly part of "Property") and 
         "user-configurable schedule" (mistakenly part of "User agent".

Edit 20) In the definition of "Transformation", remove the phrase about
         what conversion tools do and just link to "conversion tools". 
        

Cheers,

   - Ian

-- 
Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
Tel/Fax:                     +1 212 684-1814
Cell:                        +1 917 450-8783

Received on Sunday, 12 December 1999 15:06:59 UTC