Documentation checklist

Checkpoint 1: Accessible format

This page provides information for all of the checkpoints associated with Documentation checkpoint 1, as well as links to examples for specific types of documentation.


Rationale

To ensure that all users can access documentation, you must provide documents in an accessible format. If documentation is provided in multiple formats, at least one of the formats must be accessible and the accessible version must be clearly identified.


Required development techniques

In order to meet the minimum requirements of Checkpoint 1 from the IBM Documentation Accessibility Checklist, you must meet one or more of the following techniques.

Note: The examples presented in the techniques are not exhaustive. The examples are simply meant to illustrate the spirit of this checkpoint.


General documentation examples

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.1.1 Alternative text: 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, it should be coded so that it is ignored by assistive technology.

Required tests for development technique 1.1.1

Refer to the required test techniques provided in examples for the specific document formats.

1.1.2 Text description: 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.

Required tests for development technique 1.1.2

Refer to the required test techniques provided in examples for the specific document formats.

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

1.2.1 Structure: 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.

Required tests for development technique 1.2.1

Refer to the required test techniques provided in examples for the specific document formats.

1.2.2 Text formatting: 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. The following example applies to all documentation formats.

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.

Agenda: Introduction. Tips and techniques. Demo. Review. Q&A.

Required tests for development technique 1.2.2

Manually review the markup using the editor.

1.2.3 Link Purpose: 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. Do not use the URL for the link text because it does not contain enough description 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.

Required tests for development technique 1.2.3

Manually review the markup using the editor.

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

1.3.1 Color alternatives: 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.

These examples apply to all documentation formats.

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 a document contains an image that uses color to convey information, use both color and pattern to convey the information. You should also add alternative text to the image, so that screen reader users have access to the information.

Required tests for development technique 1.3.1

Manually review the document to verify sufficient contrast between text and page background.

1.3.2 Sufficient contrast: Provide sufficient contrast between text and the page background.

In order for users with low vision to be able to read information on a screen, there has to be enough contrast between the text and background of a page. This following example applies to all documentation formats.

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.

Required tests for development technique 1.3.2

Manually review the document to verify sufficient contrast between text and page background.

1.4 Meaningful sequence: Define document reading order.

1.4.1 Reading order: 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.

Required tests for development technique 1.4.1

Refer to the required test techniques provided in examples for the specific document formats.

1.5 Forms: Define form element labels.

1.5.1 Form labels: 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, which helps the user complete the forms correctly.

Some formats such as simple text-based documents and PowerPoint do not support the ability to add form fields.

Required tests for development technique 1.5.1

Refer to the required test techniques provided in examples for the specific document formats.

1.6 Tables: Identify table cells and relationships between cells.

1.6.1 Table headers: Identify row and column headers for data tables.

Do not use tabs, “/” or spaces to arrange tabular information. Instead, use data tables to display tabular data. Row and column headers enable screen readers to provide information to blind users about the relationship of data cells in a table. 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.

Required tests for development technique 1.6.1

Refer to the required test techniques provided in examples for the specific document formats.

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

1.7.1 Flashing content: 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.

Required tests for development technique 1.7.1

Manually review to verify images do not flash more than 2 times in one second period.

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

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

Screen reader users must read documents in sequential order, unless you provide a more accessible way for them to navigate your document. Using headings, sections, bookmarks, or a table of contents in your document increases the efficiency of your users. These navigational methods allow screen reader users to go directly to the specific sections that they would like to read.

Required tests for development technique 1.8.1

Refer to the required test techniques provided in examples for the specific document formats.

1.9 Language of Page: Define the default language.

1.9.1 Language definition: 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.

Required tests for development technique 1.9.1

Refer to the required test techniques provided in examples for the specific document formats.


Recommended development techniques

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


Required test techniques

Test Preparation

  1. Before starting, verify that you are using the correct documentation checklist. This checklist is used for all types of documentation except for Web-based documentation. (For that, see the Web checklist).
  2. 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.
  3. Analyze the document to see what types of elements are used. Plain text requires very little testing, but the following items require special focus in your test: images and structural elements, such as headings and lists, data tables, links, form fields, color, and complex page layouts.
  4. 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

Test Steps

The following sections contain generic techniques for testing documentation.


Step 1: Preliminary quick test using development techniques
Compliance criteria for the preliminary quick test using development techniques.
Action Results
Using the documented development (authoring) techniques, verify the following, when applicable:
  1. Verify the document language is set properly, if option is available.
  2. Verify all images have meaningful alternative text, or null alt text for decorative or redundant images.
  3. Verify that for all complex images, a text alternative is provided to fully describe the meaningful information, and the alt text for the image describes where to find the full text alternative.
  4. Verify that structural elements are coded using the proper structures, according to the document type. (Headings, lists, data tables, etc. are coded using the proper structural tags, and not with formatted text.)
  5. Verify that link text is meaningful for all links and unique for each different link.
  6. Verify the reading order / Tab order is set properly, in cases where that can be determined.
  7. Verify for documents over five pages, a long document navigation method is provided.
Pass:Fail:

Step 2: Keyboard navigation
Compliance criteria for Keyboard Navigation
Action Results
This step applies only to embedded elements that are not controlled by the document application. (For example, if you embed a video object in a Word document, Word does not control the video element.) Pass:Fail:

Step 3: Text formatting, color, and contrast
Compliance criteria for Text formatting, color, and contrast
Action Results
Verify the following text formatting and color requirements.

  1. Verify that color is never used as the only way to convey meaning (as in, the items in red…)
  2. Verify that text formatting is never used as the only method to convey information (as in, the items in bold…)
  3. Verify that sufficient contrast is provided by default between the text and the page background. The background color should provide sufficient contrast, and no patterned backgrounds should be used.
Pass:Fail:

Step 4: Blinking and Flashing elements
Compliance criteria for blinking and flashing elements
Action Results
This step applies only if your document contains blinking or flashing elements.

  1. Verify that no content flashes or blinks at a rate faster than two times per second.

Here is how to test this:
Pass:Fail:

Step 5: Screen reader
Notes on screen reader testing:Compliance criteria for the screen reader
Action Results
Using a screen reader, verify the following. Pass:Fail:



©2012 IBM Corporation

Last updated November 1, 2012