Re: draft documentation techniques

Hi Kitch!
I've some comments and or observations in your fine message below.
they begin with dp


Kitch Barnicle wrote:
> 
> Hi Folks,
> 
> I've created very rough draft of techniques for checkpoints 4.1.2 and
> 4.1.3. I wanted to send it out to see if I am on the right track. So please
> comment freely. I do think we need to define what we mean by documentation.
> Some of my colleagues have suggested that documentation refers only to
> "user manuals" and others have suggested that documentation includes
> "everything that gives the user instructions" including manuals, the help
> system, tooltips, and context sensitive help. 
dp I'd also add the www pages <g>
> As I said in an earlier
> message, I had been considering help systems as part of the documentation
> but then the issue of content versus interface comes up. I'm sorry if I
> seem to be making this more complicated than it should be.
> 
> -Kitch
> 
> Documentation -
> 
> Checkpoint 4.1.2 [Priority 2]
> Ensure that product documentation is available in at least one accessible,
> open standard electronic format (e.g., HTML, XML, ASCII).
> 
> 1. Electronic documentation
> 
> Electronic documentation created in open standard formats such as HTML and
> ASCII can often be accessed in the user's choice of application such as a
> word processor or browser. Accessing documentation in familiar application
> could be especially important to users with disabilities who must first
> configure a user agent to meet their needs or configure a user agent to be
> compatible with assistive technology. Electronic documentation should NOT
> be provided in proprietary formats such as PDF.
dp add learn the functions of as well as configure please?  Also, you
should either give no or more than one example of a declinitive format
such as pdf?
> 
> Documentation created in HTML should follow the <link>Web Content
> Accessibility Guidelines </link>
> 
> [How much detail should we include regarding content structure eg. describe
> figures, avoid columns etc?]
dp There are standard documentation practices which we should perhaps
point to but at the least don't say click.
> 
> 2. Alternative Formats
> 
> Users with print impairments may need or desire documentation in
> alternative formats such as Braille, large print, or audio tape. User agent
> manufacturers should provide user manuals in alternative formats upon
> request. Documents in alternative format documents can be created by
> agencies such as Recording for the Blind and Dyslexic (www.rfbd.org) and
> the National Braille Press (www.nbp.org). [Can we refer to specific
> agencies? What about international agencies?]
dp We can refer to a list of sources here and make it clear that it is
the responsibility of the developer to make necessary arrangements or
to provide accessible guidance to customers.
> 
> 3. Text of documentation
> 
> User instructions should be created in an input device-independent manner.
> Provide instructions for using or configuring the user agent in a manner
> that can be understood by a user of any input device including a mouse or
> keyboard. For example, "Click on the Home button on the toolbar or select
> "Home" from the Go menu to return to the Home page. "
> 
> Checkpoint 4.1.3 [Priority 2]
> Describe product features known to promote accessibility in a section of
> the product documentation.
> 
> 1. Index
> Include terms related to product accessibility in the documentation index
> (e.g. accessibility, disability/disabilities)
> 
> 2. Table of Contents
> Include terms related to product accessibility in the documentation table
> of contents (e.g. Features that promote accessibility)
> 
> 3. Include instructions on how to modify all user configurable defaults and
> preferences.
> (e.g images, video, style sheets, and scripts) [Should we list every user
> configurable feature?]
dp Whatever the manual/documentation does.
> 
> 4. Include a list of all keyboard shortcuts in the accessibility section of
> the documentation.
> 
> Maybe some of the product developers on this list can offer additional
> suggestions.
dp Thanks!
-- 
Hands-On Technolog(eye)s
Touching The Internet
ftp://ftp.clark.net/pub/poehlman
http://poehlman.clark.net
mailto:poehlman@clark.net
voice 301-949-7599
Dynamic Solutions Inc.
Best of Service for your small business network needs
http://www.dnsolutions.com

Received on Wednesday, 3 March 1999 15:04:09 UTC