# Writing Accessible Documentation

This chapter provides some basic guidelines for writing GNOME documentation for users with disabilities.

## Assistive Technologies

Wherever possible, consider the requirements of the following groups of users when you write documentation:

- Users with cognitive impairments

- Blind users and users with other vision impairments

- Deaf users and users with other hearing impairment

- Paralyzed users and users with impaired motor skills

Assistive technologies exist to help computer users with various disabilities. An example of assistive technology is the screenreader, which blind people use to view a GUI and read online text. A screenreader normally translates text into synthesized speech or a refreshable Braille display.

## Information Design Considerations

Consider the following factors relevant to disabled users when you write documentation:

Text blocks

  Long text blocks can be difficult to read for people who use screenreaders. Also, readers whose first language is not standard English, including some deaf people, can find long text blocks difficult to understand. Keep your text blocks short. See for more information.

Graphics

  Do not overuse graphics, especially when you write online Help. A graphic that merely repeats a text message can frustrate someone who is using assistive technology to read the Help. Provide descriptions that do not require graphics. To test whether you need a graphic, remove the graphic, then check whether you can still work out what to do. If you need to use a graphic, make sure that you include a text equivalent of the graphic. See for more information.

Tables

  Tables can cause problems for screenreaders that read the content of all the cells as a single, continuous line of text. Use tables for genuinely tabular information only. Do not use tables merely as a layout technique. Ensure that tabular information makes sense if you read the cells in sequence from left to right, starting from the top left cell in the table.

## Accessible Writing Techniques

The following guidelines can help you to develop an accessible writing style:

- Write concise descriptions to help people with cognitive, vision, and hearing impairments. As recommended elsewhere in this guide, keep sentences to one idea. Do not ramble.

- Keep the number of steps in procedures to a minimum. More than seven procedural steps can create problems for all users, but pose additional difficulties for people with cognitive impairments.

- Do not use directional instructions, if at all possible, such as above, below, left, right. Users who are using a screenreader might have difficulty finding the directions on screen. Some users with cognitive impairments might have difficultly understanding the spatial concepts.

- Emphasize important information near the beginning of the text, so that blind users and users with cognitive impairments can assess whether they need to read further.

## Text Equivalents for Graphics

Graphics such as illustrations, icons, photos, screenshots, and thumbnails all require text equivalents for use with assistive technologies. Each text equivalent should briefly identify the graphic and, if appropriate, describe any functionality that the image represents. The text equivalent must be brief, descriptive, and accurate. You need to include as much information as possible into the fewest number of characters without sacrificing intelligibility

### Creating Text Equivalents

A text equivalent should describe the visual appearance of the graphic. The text equivalent can also include instructions on how to take an action, such as how to select options in a dialog. Ideally, a text equivalent provides the user with the same information as the original graphic. To find out how to implement text equivalents in your documentation, see the GNOME Handbook for Writing Software Documentation.

### Writing Good Text Equivalents

To comply with Part 1194.22 in Section 508 of the Rehabilitation Act: Electronic and Information Technology Accessibility Standards, documentation must include a text equivalent for each graphic in documentation.

Follow these guidelines when you write text equivalents:

- At a minimum, include the graphic content and the label of the item in the graphic. For example, "Run Application dialog."

- If the contents of the graphic are not complex, describe the contents of the graphic. For example, "Run Application dialog. Contains command drop-down combination box, Browse button, Run in terminal check box. Contains Run, Cancel, Help buttons."

- If the contents of the graphic are complex, summarize the contents of the graphic. For example, "Miscellaneous tabbed section. Contains controls to set miscellaneous Sawfish options. Contains Done, Cancel buttons."

- If the order of use of elements in a graphic is not clear, describe the elements in top-to-bottom, left-to-right order.

- If the graphic is annotated, list the callouts in order of the elements that are illustrated. This is not necessarily the same as the order in which the callouts appear. For example, "Crux window titlebar. Callouts: Window Menu button, Titlebar, Minimize, Maximize, Close Window buttons."

## More Information About Accessibility

For more information about accessibility topics, read the following documents:

- Accessibility Quick Reference Guide, Sun Microsystems

- RNIB Accessibility Web Design, Royal National Institute for the Blind

- Guide to Writing Accessible HTML, Jan Richards

- Web Content Accessibility Guidelines 1.0, W3C Recommendation 5-May-1999