Documentation checklist

This page provides specific examples to implement the documentation techniques for accessible documents.

Some users may not be able to access documentation if it is not in an accessible format. If documentation is provided in multiple formats, at least one of the formats must be accessible.

Back to top

The following techniques are the minimum required to meet Checkpoint 1 from the IBM Documentation Accessibility Checklist. Follow the general techniques on this page along with links to examples for specific types of documentation:

• Examples for Lotus Symphony documents
• Examples for Lotus Symphony presentations
• Examples for Lotus Symphony spreadsheets
• Examples for Microsoft Word
• Examples for Microsoft Powerpoint
• Examples for Microsoft Excel

1.1 Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose.

1. Provide alternative text for all images.
   
   If an image is meaningful, provide a short text alternative that provides equivalent meaning. When a screen reader encounters the image, it will read the text alternative. If an image is pure decoration or only used for visual formatting, implement it so it can be ignored by assistive technology.
   
   
2. Provide a text description in addition to alternative text for complex charts and graphs.
   
   Alternative text may not be sufficient to describe complex images such as graphs and charts. In that case, provide a more complete description in surrounding text or if supported, use the long description.

1.2 Information and Relationships: Define information, structure, and relationships.

1. Define document structure.
   
   For document types that support this feature, use structure (e.g. headings, lists, sections) instead of presentation (bold, large fonts) to define elements. This enables screen readers to convey information about the document structure to blind users. Simple text-based documentation formats such as Notepad do not provide options to define document structure.
   
   Syntax diagrams are usually provided as railroad diagrams, but this format is not accessible to someone using a screen reader. An accessible format such as dotted decimal or BNF (Backus-Naur) must be provided in addition to the railroad diagrams.
   
   
2. Do not use text formatting as the only way to convey meaning.
   
   When text formatting (e.g. bold, italics) is used to convey meaning, it is not accessible to someone listening to a document with a screen reader. When using text formatting to convey meaning, provide another way of making the information available.
   
   Example 1
   In the screen shot below, bold is used as a way to indicate where the user is in the overall agenda of the presentation. Since bold text is not accessible to all users, an asterisk has also been added to convey that you are now going to cover the Demo portion of the presentation.
   
   
   
3. Identify the purpose of each link in the link text.
   
   Someone using a screen reader may list all links on the page for easy navigation. Links must be understandable when read out of context. When the link is the URL, it is not descriptive enough to understand the target of the link.
   
   Example 2
   If the documentation directs the user to http://www.ibm.com/able for more information on accessibility, it is difficult for someone listening with a screen reader to understand the destination of the link. A better method is to make the link text for the URL IBM Accessibility. The destination is clear and the link will be understandable when read out of context in the screen reader links list. Each different URL or link should have unique link text. Links to the same URL can have the same link text.
   
   Example 3
   For documents that will be printed, it is acceptable to spell out the URL but the descriptive text is also needed in the source format. As mentioned, it's best to make the descriptive text the link text and not the URL so that when the screen reader user selects the option to list the links in a document only the descriptive text will be read instead of the URL. For example: IBM Accessibility http://www.ibm.com/able.

1.3 Color & contrast: Any information that is conveyed by color is also evident without color.

1. Do not use color as the only way to convey meaning.
   
   When color is used as the only way to convey meaning, the information is not accessible to someone who is colorblind or someone using a screen reader. When using color, provide another way of making the information available.
   
   Example 4
   If required user settings are listed in red and optional settings are displayed in green, preface the setting with an asterisk or other cue so someone who is colorblind or someone who is using a screen reader will also be able to identify the required commands.
   
   *=Required settings
   
   Preferences
   * Use accessibility keyboard navigation
   

   Application
   Mail
   
   Do not prompt when exiting application

   Calendar
   
   
   Example 5
   If color is used within an image to convey information, use color and pattern to convey the information. In addition, provide appropriate alt text for the image so the information will be accessible to someone using a screen reader.
   
   
   
2. Provide sufficient contrast between text and the page background.
   
   Someone with low vision needs high contrast between text and the background to read information on the screen.
   
   Example 6
   This text provides sufficient contrast because it is black text on a white background.
   This text does not provide sufficient contrast because it is light blue text on a white background.
   

1.4 Meaningful sequence: Define document reading order.

1. Define document reading order.
   
   For document types that support this feature, ensure that document elements are presented in a logical reading order. Simple text-based documentation formats such as Notepad do not provide options to define reading order since the document structure is not complex.

1.5 Forms: Define form element labels.

1. Provide an accessible label for form fields.
   
   For document types that support this feature, label form fields so the text is associated with the input field. Labels enable screen readers to provide the relationship between the text label and the form field so forms can be filled out correctly by someone using a screen reader.
   
   Some formats such as simple text-based documents and PowerPoint do not support the ability to add form fields.

1.6 Tables: Identify table cells and relationships between cells.

1. Identify row and column headers for data tables.
   
   Do not use tabs and / or spaces to arrange tabular information. Instead, data tables should be used to display tabular data. Row and column headers enable screen readers to provide information about the relationship of data cells in a table to blind users. When a document format does not support the ability to define row and column headers, data tables should not be used in the documentation.
   
   Some formats such as simple text-based documents do not support the ability to define row and column headers. Tables should be avoided in those types of documents.

1.7 Threshold violations: Do not include text or images that flash more than 2 times in a one second period.

1. Do not include text or images that flash more than 2 times in a one second period.
   
   Text that blinks or flashes can cause photosensitive epileptic seizures in susceptible individuals, particularly if the flash has a high intensity and is in the frequency range between 2 Hz and 55 Hz. This includes flashing text, turning graphics on and off or repeatedly changing between different images on the screen.
   
   Example 7
   Flashing and blinking content should be avoided. If provided as part of the documentation, ensure that the flashing is not in the range between 2 Hz and 55 Hz.

1.8 Navigation: Provide an accessible method to navigate long documents.

1. Provide an accessible method to navigate long documents.
   
   Screen readers must read documents in sequential order unless authors provide an accessible method to navigate documents (e.g. headings, sections, bookmarks, table of contents). These methods help make the user more productive because they can skip to specific sections of the document that they want to read when using assistive technology to read documentation.

1.9 Language of Page: Define the default language.

1. Define the language of the document.
   
   For document types that support this feature, define the primary language of the document so screen readers can correctly read the content. Simple text-based documentation formats such as Notepad do not provide options to define the document language.

Back to top

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

• Spell check all documents before distributing them to users.
• Implement non-essential elements (e.g. running headers or footers, numeric only page numbers) so screen readers can ignore them.

Back to top

Test the documentation to ensure that it complies with accessibility requirements.

Reminder: These are generic techniques for testing documentation. For Lotus Symphony Documents, Lotus Symphony Presentations, Lotus Symphony Spreadsheets, PowerPoint, Word and Excel documents use the test techniques listed on those technique pages.

Best practice: It is highly recommended that you complete all other testing and fix all known errors before testing with a screen reader. This will reduce the number of screen reader issues.

Use the expected presentation mode for your document when testing with a screen reader. For example, use Microsoft Powerpoint slideshow mode for testing PowerPoint presentations.

Required test software

• screen reader

Techniques