Thoughts on product documentation

Working on 5.3.2 (Document Accessibility Features) brought up some 
additional thoughts that I wanted to run by the group.


  I. "Documented" vs. "Documented in the product documentation"

To begin with, is there a difference between a product's documentation 
describing a feature, vs. the feature being documented? In particular, 
if a third party describes the features on their Web site or in a book 
about the product, would that be enough make the product compliant with 
letter letter of this success criterion, even though it's against its 
spirit?

In case the group thinks that could be a problem we could address it in 
either of two ways:

   1. revise the SC to explicitly use the terms "product documentation"
      or "primary product documentation, as in "The product
      documentation describes all user agent features that benefit
      accessibility", or
   2. define "documented" such at it applies only to the official
      product documentation.

Which leads us to...


  II. Different levels of documentation

However, either way we should probably clarify what we include as 
product documentation as used throughout 5.3, either through a glossary 
entry, or notes in the Implementing document, or both. Some categories 
of documentation--not all of which we might consider "product 
documentation" for our purposes--include:

   1. in-product electronic help, whether the content is fed from local
      files or from the Web
   2. product documentation that is delivered with but generally
      accessed from outside the product, including PDF, HTML, etc.
   3. "readme files" which are usually more technical and less polished,
      and may even be unformatted so they can be changed after the
      deadline for the main documentation has passed
   4. post-release documentation such as online "knowledge bases" and FAQ
   5. online discussion forums with user-provided content
   6. third-party documentation, including online tutorials
   7. commercial documentation, such as aftermarket books by the
      manufacturer or other publishers

Off-hand, I think that when we require features to be documented it 
should at minimum be: (a) available at no extra charge, and (b) 
described in the product's primary documentation, whether that is 
installed with the product or accessed via the Web. Also important, but 
possibly above the minimum: (c) features that can affect the user's 
ability to install and start the product should be available before 
purchase and installation.


  III. Documentation in plain text

Finally, during the most recent conference call we decided to go with 
"5.3.1 Accessible documentation: The product documentation is available 
in a format that conforms to WCAG 2.0 Level 'A' or greater", which I 
really like. However, it is not uncommon for user agents to ship with 
some documentation as plain text files, most commonly installation 
instructions (e.g. Firefox's readme.txt) or license agreements (e.g. 
Opera's license.txt). These are shipped a plain text in order to allow 
them to be easily changed up to the very last minute and viewed without 
any special software. If "product documentation" includes readme files, 
we would pretty much be requiring those to be HTML instead of (or in 
addition to) plain text. Is that reasonable?

If not, we could address this by making an explicit exception in the SC 
for readme files (assuming we could define them) or allowing plain text 
as long as it meets some minimum criteria (e.g. shorter than a minimum 
length, formatted according to the ICADD Level 0 standard, etc.).

     Thanks,
     Greg