Authoring Accessible Documentation

– Mugdha Vairagade

The software application you document is accessibility-compliant, but not the documentation you author? Then read on.

According to Wikipedia, accessibility is a term used to describe the degree to which a product, device, service, or environment is accessible by as many people as possible. Specifically, accessibility indicates how easily people with disabilities or special needs can access and use anything; ­ be it elevators, home appliances, websites, or software applications.

Today most software applications, from Office suites to authoring tools, either include accessibility features or support assistive technology. That is,

• Software applications have in-built accessibility features that enable the people with disabilities use those applications, such as text magnifiers, text-to-speech UI readers, voice-based navigation and so on. Or,
• Software applications are engineered in such a way that people with special needs can use special tools, broadly termed as assistive technology, to interact with these applications. The special tools include screen readers, Braille display, voice-based browsers and so on.

Government regulations (for example, section 508 Rehabilitation Act,1973 of United States) either encourage or make it compulsory for software vendors to make their applications accessibility-compliant. Market demands also dictate implementation of accessibility-compliance to reach a wider customer base. Accessibility-compliant applications not only help users with disabilities but also the users who want to use assistive technology as alternate means of application interaction.

With software applications implementing accessibility guidelines, it is only natural that their documentation too should be accessible. At present, organizations such as IBM, Apple, Oracle, and many others have set up accessibility guidelines for their documentation (see the Resources section). The documentation accessibility guidelines are similar to the Web Content Accessibility Guidelines set by World Wide Web Consortium (W3C), and are easy to implement.

Here are a few generic guidelines that you can use to make your documentation accessible to a larger audience via assistive technology:

1. Carefully analyze the audience of the documentation you are to author. Does that include people with special needs? Identify the groups of special needs users for whom the application and documentation is relevant. For example, an image editing application may not be useful for people with visual impairment, but can be used by people with speech or hearing disabilities. Therefore, the corresponding documentation should be written to be accessible to the later two groups.
2. Make documentation text easy to read and convert for assistive technology (text-to-speech reader, Braille browser, voice-based browser and so on). Take the following steps:
   1. Keep the formatting separate from text using style sheets. Then the assistive technology is able interpret and present the style information as per its own capability. For example, assistive technology may display different font and larger font sizes.
   2. If possible, use markups to indicate special characters, notations, and mathematical expressions. For example, use MathML for mathematical expressions in Online Help. Also ensure that special characters and notations are pronounced correctly by text-to-speech readers.
   3. Avoid using tables to specify page layouts. Assistive technology has difficulties interpreting document structure and flow of a document that uses tables for page layout.
   4. Online Help and DITA documentation authored using pure well-formed HTML, XHTML, or XML are best-suited for assistive technology. For such documentation, write content using only generic acceptable HTML/XML tags and avoid browser-specific tags/scripts. Also, follow points a, b, and c mentioned above. These steps help create documentation that is compatible with most tools used by people with special needs.
3. Avoid using visualization and colors alone to indicate something in documentation. For example, relying only on user interface screenshots to explain steps in a process, or using colors to indicate areas in charts or graphs makes it difficult for people with vision impairment to understand such documentation. The best approach in this case is to use alternative text or descriptive captions for images, and using text labels instead of colors for indication or highlighting.
4. When using tables, identify table cells and relationships between cells with column and/or row headers. Refer to Web Content Accessibility Guidelines (see the Resources section) to know more about creating tables readable by assistive technology in Online Help.

For other documentation types, include a short description before the table, to explain the purpose of the table and the table structure. For example, “In the Table 4.1 Variable Values, the column Variables contains variable name. The column Default Value contains the corresponding default values, and the column Range contains the corresponding range of values.”

1. If publishing a PDF, take steps to make the PDF accessible – using document structure tags, bookmarks, and text-to-speech capability. See Resources for PDF Accessibility Guidelines.
2. If it is not possible to provide one single set of accessibility-compliant documentation for both the general and special-needs audience, then create a separate set of accessible documentation, authoring all content in suitable form for assistive technology.
3. Make documentation easy to navigate; include search, bookmarks, and tags.
4. Provide keyboard shortcuts as alternative to any mouse actions required.
5. Provide text transcripts along with audio and video content. Also, provide controls to start, pause, or slow the speed of such content.
6. Like testing software for bugs, test documentation for accessibility. At present, various web accessibility checker tools are available (see the Resources section). Use them to test the Online Help documentation.

For PDFs, use Adobe Acrobat’s accessibility checks and reports feature. Microsoft Office 2010 also has in-built accessibility checkers to help you author accessible documents and presentations (see the Resources section).

This generic set of guidelines helps you to author all types of documentation that is accessible from most assistive technology tools. Do go through the organization-specific guidelines listed in the Resource section, to learn how to make a specific documentation type accessible.

Resources:

• W3C Web Content Accessibility Guidelines 2.0 (http://www.w3.org/TR/WCAG20/)
• Web Accessibility Initiative (http://www.w3.org/WAI/)
• Web Accessibility Checker Tools (http://www.w3.org/WAI/ER/tools/)
• PDF Accessibility Guidelines (http://www.adobe.com/accessibility/products/acrobat/pdf/A9-pdf-accesibility-overview.PDF)
• IBM Human Ability and Accessibility Center (http://www-03.ibm.com/able/guidelines/documentation/accessdoc.html)
• Oracle’s Accessibility Program (http://www.oracle.com/accessibility/index.html)
• Documentation in Accessible Formats for Microsoft Products (http://www.microsoft.com/enable/products/docs/)
• Apple Accessibility Overview (http://developer.apple.com/mac/library/documentation/Accessibility/Conceptual/AccessibilityMacOSX/OSXAXWhy/OSXAXwhy.html#//apple_ref/doc/uid/TP40001078-CH206-TPXREF101)

About the author:

Mugdha Vairagade is a Pune-based senior technical writer with 10 years of experience and specialization in Telecom domain. She became interested in documentation accessibility after learning about accessible Telecom services for people with disabilities.
You can reach Mugdha through her website (www.techatom.in), her LinkedIn profile (http://in.linkedin.com/in/mugdhav), or twitter (www.twitter.com/mugdhav).

About the illustration:

Used with permission from Vishesh Gupta.

Edited:

The link to the WCAG guidelines was updated to the link to version 2.0 as per Karen’s comment.