[Editorial] Two glossary comments

Hello,

I finally read the glossary of the 23 March 2001 draft [1].
I don't have any significant complaints (and will make a few
minor editorial clarifications in the next draft).

Two points caught my eye that I wanted to mention to the WG.

1) The definition of "documentation" reads:

   "Documentation refers to all information provided
    by the vendor about a product, including all product
    manuals, installation instructions, the help system, 
    and tutorials."

   This sounds too normative to me. Our documentation 
   *requirements* are expressed by Guideline 12. Those
   five checkpoints make requirements about (1) what must
   be in the documentation and (2) the accessibility of
   the documentation.

   I think the definition needs to be written in a manner
   that doesn't suggest that it adds requirements (e.g.,
   that the vendor is required to write tutorials in order
   to conform). 

   Also "all information provided by the vendor about a product"
   is far too broad. This might include press releases, TV
   commercials, etc.

   As for other features, the claimant may decide to include
   or exclude different pieces of documentation based on whether
   they conform. The only *required* documentation is that required
   by the checkpoints of Guideline 12.

   Therefore, I propose the following change to the definition:

   <NEW>
   "Documentation refers to information that supports the
    use of a product. This information may be found in product
    manuals, installation instructions, the help system, 
    tutorials, etc. Documentation may be distributed; it may
    be delivered on CD-ROM or available on the Web. Refer to
    Guideline 12 for information about documentation requirements.
   </NEW>

2) We define "document source view" but we don't use it
    in any of the checkpoints. Checkpoint 2.2 says "provide
    a view of the text source." 

    I propose to leave 2.2 as is and to delete "document source
    view" from the glossary.

 - Ian

[1] http://www.w3.org/WAI/UA/WD-UAAG10-20010323/
-- 
Ian Jacobs (jacobs@w3.org)   http://www.w3.org/People/Jacobs
Tel:                         +1 831 457-2842
Cell:                        +1 917 450-8783

Received on Wednesday, 28 March 2001 14:11:05 UTC