Re: Thoughts on product documentation

On Thu, 29 Apr 2010 03:00:31 +0200, Greg Lowney  
<gcl-0039@access-research.org> wrote:

> 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?

Yes, but I think for us the primary difference is that the conformance  
claim then has to include the product, and a pointer to the third-party  
extras required to make it work. Another example case would be Opear's  
help, which is by default online and not shipped with the browser itself -  
that would need to be stated in a conformance claim.

...
>   II. Different levels of documentation
...
> Off-hand, I think that when we require features to be documented it
> should at minimum be: (a) available at no extra charge,

While that is generally desirable, I don't think it is a requirement. If  
you have to pay extra, then the conformance claim has to note which things  
you need, so it should be clear that they are extras.

> ... 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.

Not sure that they should be available before purchase, but I think they  
must be available before installation at the minimum.

>   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?

Hmm. Interesting question. I haven't done a conformance test of a license  
(although I think we have all our documentation available as HTML, with  
some of it additionally plain text) - is it really necessary to be HTML to  
conform?

> 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.).

Yeah, although I would prefer not to go down this path really...

cheers

Chaals

-- 
Charles McCathieNevile  Opera Software, Standards Group
     je parle français -- hablo español -- jeg lærer norsk
http://my.opera.com/chaals       Try Opera: http://www.opera.com

Received on Thursday, 29 April 2010 09:19:17 UTC