Writing Accessible Technical Documentation

Title Slide

DANIELLE: In this presentation, we’re going to show you how to make sure your Word documents can be fully accessed by all users and meet both the Americans with Disabilities Act (ADA) and federal Section 508 standards. We’ll define accessibility and go through the steps in Word for things like text, images, and links. To begin, let’s define accessibility.

What is Accessibility

DANIELLE: Accessibility ensures everyone can perceive, operate, and understand information and technology. ADA Title II & III refer to the public sector responsibility for non-discrimination/equal use of products and services. Section 508 is a part of the Rehabilitation Act of 1973. It was updated in 2018 to address the latest in Information and communication technology. These standards provide requirements for how to make your products and documentation accessible to everyone, regardless of ability.

Disability Considerations

DANIELLE: The disability considerations for technical documentation include visual, hearing, and mobility. Documentation must be accurately read by screen readers and refreshable Braille displays, as well as proper color and design for those with sight disabilities who do not use assistive technology. If your documentation or help content contain audio elements, the audio content must be duplicated with captioning and descriptions for those with hearing disabilities. Mobility disabilities are often ignored where documentation is concerned, but mobility can be a serious concern for those who cannot use a mouse. Users must be able to access all information in the document through keyboard controls and other mobility assistive technology. Proper formatting is key to creating fully accessible technical communication.

Accessibility for Microsoft Word Documents

ERIN: For simplicity sake, this presentation shows how to write accessible documentation in Microsoft Word. Most of us have experience using Word and the same accessibility principles and techniques discussed here also apply to other TechComm software, like FrameMaker, RoboHelp, and Madcap Flare. 

To start, make sure you are using the latest version of the software. Use an established accessible design template, or create your own accessible template with standard heading styles. Don't use ad hoc formatting, because assistive technology has trouble reading custom styles. Make sure your file is not protected. If the file is protected, assistive technology cannot read the file. And lastly, make sure that you save the file with a descriptive file name to help people correctly identify the file.

Check Headings and Order

ERIN: First, click the View tab located in the heading bar. From there….

The navigation outline will help you identify errors in your headings formatting and shows you the order that assistive technology will read the document.

List Column and Formatting

DANIELLE: If you include lists and columns in your document, use the formatting tools in Word. Assistive technology cannot determine meaning if you try to format without using these tools, such as typing in the numbers or using dashes. List settings in Word has bullets, numbers, and levels you can use to correctly set the format. Word also has a Columns option. Don’t use tabs or spaces to create your own columns.  

Table Formatting

DANIELLE: If you include tables in your document, those also must be formatted correctly to be accessible. Don’t wrap text, merge cells, or split cells. If you have complex data tables, it’s best to convert the document to a PDF and use the accessibility features there. PDF accessibility tools allow you to label the cells in a table so that assistive technology knows how to read the table content.

Language Considerations

ERIN: For documents including more than one language, assistive technology such as screen readers may not correctly pronounce the words unless the text is formatted for the correct language. To do this, highlight the text in the secondary language, select the Review tab, select Language, and Set Proofing language. Choose the correct language from the list. 

Accessible Links

ERIN: If you include hyperlinks in your documents, create a descriptive link name. This is the same as creating a descriptive name when saving the document. When you use a descriptive name, the AT conveys to the user exactly where the link goes and what the user will find there. For example, instead of using “Click here to learn more”, use "See the TCDojo homepage (where TCDojo is the link) for more information on upcoming sessions." To change the name of the link, right-click on it, click Hyperlink, and edit in the Text to display field. 

Headers and Footers

ERIN: Headers, footers, and watermarks present a challenge for assistive technology. AT doesn’t automatically pick up on these features. If your document requires such features, as our Government software manuals do, make sure to include this information somewhere in the document body text, such as the title page. The example here shows the same information in the footer as in the title page.  ​

Object and Image Alt Text

DANIELLE: If you include images in your documents, include Alt text. Alt text is a description of the image that is read by assistive technology. This text conveys the purpose of the image and lets the user know how the image relates to the text. In Word, right-click the image and select Alt text. Describe the image in 125 characters or less. For the image itself, use editing tools (such as Snag-It) to focus on the exact topic area (instead of the full window) and do not add anything to the image such as red circles or boxes, arrows, or text call-outs. NEVER use images of tables. AT cannot read this and alt text doesn’t allow enough characters to type out the table information. The next slide has a few examples of what NOT to do.

Non-compliant Images

DANIELLE:

• First image, screenshot of a flow chart. AT can’t describe each box in the flow chart because it’s just an image of the chart. The alt text box isn’t the place to type out so much information.
• Second image, text call-outs. Use bullet points before or after the image.
• Third image, too many red boxes. Besides looking tacky, the color may pose a problem for some users. Use focused screenshots or write the text to explain the order such as, “From left to right, these are the functions…”
• This isn’t just for those with visual impairments. Those with physical motion limits who rely on keyboard commands to navigate through documents and web pages need to be able to move in a linear fashion to access all information and functions. 

How to Add Alt Text

DANIELLE: As we mentioned in a previous slide, to add the alt text to an image right click and select Edit Alt Text or right click and select Format picture, then Alt text depending on your version. This screenshot shows what the Alt text dialog looks like. Type the text in the text box. If the image is purely decorative such as a logo, click the Mark as decorative checkbox. Though these instructions are for Microsoft Word, the process is similar in other brands of documentation software.

Object and Image Formatting

DANIELLE: Image placement is also a factor in making documents accessible. Make sure all images are in-line with the text so that assistive technology can read the image alt text in the order it should appear in the document. Here we provide the steps to place an image or object in line with text in Microsoft Word, but the steps are similar in other brands of documentation software. So, select the image, go to Picture Tools, format, and position. Click the In line with text option.

Visual Formatting

ERIN: Color formatting is also important in making documents accessible. Some users may have color-blindness and some color combinations cause difficulty by making the text seem blurry. Some users may not be able to read smaller print, especially with certain background colors. Never only use a color to denote something, such as red to signify something is urgent, unless the actual word “urgent” is there. Those with visual disabilities, including color blindness, will not be able to tell what you are trying to communicate if you are only using color to denote something. So make sure that all colors and visuals are adequate for all users and make sure the contrast ratio between text and background is sufficient. There are several free color analyzers you can use to help you check your color contrasts. We’ve provided one here that we’ve used in the past, but feel free to do your own research and use the tool that works best for you.

Color Contrast Standards

ERIN: This chart shows good and bad color contrast examples. It also provides the recommended color ratio for the colors used. You can use a color analyzer, like the one mentioned in the last slide, to test your use of color for accessibility in your documentation.

Multimedia Considerations

ERIN: Any added audio, video, or multimedia files embedded into a document must have additional written information such as a complete text transcript or description if it’s only audio or video. If it’s multimedia (meaning audio and video), use captions for the audio and descriptions for the visuals. 

PDF Accessibility Check

ERIN: Many of us deliver documentation to end users in PDF form. The secret to creating an accessible PDF is to create a well-formatted, accessible source document first. In this presentation we've shown how to do that in Word, but the same principles apply when working in FrameMaker, Madcap Flare, RoboHelp, or any other documentation software.

After you've converted your documentation to PDF, there are a few setup steps to perform in the PDF and then you can apply the PDF Accessibility Check. This is an accessibility checking tool that is provided in Adobe Acrobat.

The tool searches the document for formatting and items that do not comply with accessibility standards. It flags all of these instances and provides a report that can be used to remediate the document's accessibility problems.

This report is also a great way to identify common formatting errors in your documentation. The best practice to fix accessibility errors in PDFs is to fix the errors in the source document first, and then re-generate the PDF and re-run the Accessibility check.

For those of you interested in more information on PDF accessibility, we're teaching a half day workshop on Writing for Accessibility and Privacy Protection at the STC Summit 2020 in Seattle this year. We'd love to see you there!

Thanks

DANIELLE: Thanks for letting us present this session on accessibility in technical documents. We’re honored you asked us to do this! We’re open to questions, if anyone has them.

Contact Us

DANIELLE: If you think of questions or comments and want to contact us, here’s our information. Thanks again for having us.