Documentation, Online Information and Help

When developing documentation for your application in HTML, please follow the IBM Web accessibility checklist.

The World Wide Web Consortium (W3C) publishes Web content, tool, and user agent accessibility guidelines at http://www.w3.org/WAI.

Accessible format for documentation

Provide documentation in an accessible format.

Rationale

Some users may not be able to access documentation if it is not in an accessible format.

Techniques

The GNOME Documentation System consists of DocBook, Yelp (GNOME Help Browser), Scrollkeeper (document cataloging system), and some DocBook XML tools. DocBook is a markup language, like HTML. The GNOME Documentation Project (GDP) provides DocBook XSLT stylesheets to help in the conversion of DocBook files to HTML for viewing in Yelp. However, GDP DocBook XSLT stylesheets are not required to view DocBooks in Yelp, which has its own DocBook stylesheets. DocBook source can also be converted to PDF and PostScript formats. The GNOME Handbook of Writing Software Documentation describes how to create documentation using DocBook in greater detail.

Yelp, which uses a GECKO engine, can access several different documentation systems on Linux: man pages, texinfo pages, HTML, and DocBook. Scrollkeeper, which uses an Open Source Metadata Framework (OMF), works with Yelp to provide a table of contents, search engine, and indexing capabilities.

Man pages are plain text files created using gedit or another text editor and read using the terminal command line or Yelp.

Texinfo, from the GNU project, uses a single source file, loosely based on Brian Reid's Scribe and other formatting languages , to produce output in a number of formats (dvi, html, info, pdf, xml, etc.).

At this time we haven't studied how to create accessible Linux documentation, or how accessible the different documentation formats are on GNOME is using Linux screen readers with Yelp, Firefox, or terminal emulation.

The GNOME Documentation Style Guide has a section on Writing Accessible Documentation.

• Provide application documentation in at least one or more of the following accessible formats:

  • DocBook. Need to find out how to create accessible DocBook documentation, or if it needs to be converted to HTML.

  • Accessible HTML. Follow the IBM Web accessibility checklistto produce accessible HTML.

  • Man pages.

  • Texinfo. Need to find out how to create accessible Texinfo files, or if they need to be converted to HTML.

  • Accessible PDF. Follow the IBM Documentation Accessibility Checklist Checkpoint 1and refer to Adobe's accessibility information regarding how to create accessible PDF documents. We know this is not yet accessible on Linux.

• Include text descriptions of illustrations and graphics in the documentation.
• If the documentation is not available in an accessible format, provide documentation in braille or audio cassette, upon request from the user.

Testing

Test the software to ensure that it complies with accessibility requirements. The IBM Documentation Accessibility Checklist Checkpoint 1 covers how to test documentation for accessibility. But only using Microsoft Windows, not on Linux GNOME yet.

• Test the accessibility of DocBook files using Linux screen readers and Yelp, with stylesheets and/or converted to HTML. Need to try this out with Gnopernicus and Orca to see how well it works and then add more detail.

• Test the accessibility of man pages using a Linux screen reader, both from the terminal command line and using Yelp. Need to try this out with Gnopernicus and Orca to see how well it works and then add more detail.

• Test the accessibility of texinfo files using a Linux screen reader and Yelp. Need to try this out with Gnopernicus and Orca to see how well it works and then add more detail.

• Test the accessibility of HTML files using a Linux screen reader and Yelp and/or Firefox on Linux. Until Linux screen readers and browsers (Yelp and Firefox) have implemented ATK interfaces for document objects and structures, use Microsoft Windows assistive technology such as IBM Home Page Reader, JAWS, or Window Eyes to verify that HTML documentation is accessible.

• Test the accessibility of PDF documents using a Linux screen reader with Adobe Reader on Linux and/or use the Adobe Acrobat Accessibility Checker. Until Linux screen readers and the Linux version of Adobe Reader have implemented ATK interfaces for document objects and structures, use the Accessibility Checker - Full Check in Adobe Acrobat on Microsoft Windows, or Microsoft Windows assistive technology like JAWS, Window Eyes, or IBM Home Page Reader. An accessible Linux Adobe Reader is not yet available.

See Test section Testing for Accessibillity].

Documentation for accessibility features

Provide documentation on all accessibility features as part of the regular product documentation..

Rationale

People with disabilities cannot effectively use the software if they cannot access information on how to use accessibility features. This is particularly important for keyboard access. Since most products focus on navigation with the mouse, it is not always clear how to use the product with the keyboard. All keyboard navigation which does not follow documented system conventions should be documented.

Techniques

The following techniques are required.

• Provide a section where all accessibility features are documented. The online help documentation in Lotus Notes is a good example of this technique.
• Provide a section where unique keyboard accessibility features are documented. If the software uses standard system keyboard commands for navigation, they do not have to be documented. The keyboard accessibility information could also be included as part of the general accessibility section.
• When the software provides instructions for completing tasks using the mouse, include the instructions for doing those tasks using the keyboard.

The techniques above are required; the following techniques are recommended to enhance accessibility:

• Include a keyword search and help topic item for accessibility.
• Document any shortcut keys in the software by adding the information next to the command in the pull-down menu.

• Future:' Include documentation on how to use a custom "Perk" or script for the IBM Linux Screen Reader and/or other Linux screen readers.

Testing