Web content accessibility instructions for authors

What you need to do to comply with requirements and reach more readers

The purpose of making Web content "accessible" is to ensure that all readers have equal opportunities to learn, including those who have vision or hearing impairments. Accessible content is required by federal laws and corporate policies. This article explains what these regulations require and how to write and format your articles, tutorials, and Web pages to ensure that they comply and reach more readers.


Judith Broadhurst (jbroadhu@us.ibm.com), Technical Editor, IBM

Judith Broadhurst edits for the IBM Rational Software Group, mainly articles and tutorials published by IBM developerWorks. She has worked as a technical editor for major technology companies since 1995. Previously, she was a freelance journalist who wrote feature articles for numerous national magazines, Web sites, and daily newspapers. She is also the author of a consumer-oriented book published by McGraw-Hill and chapters in three other books, all related to using the Internet.

08 July 2008

Also available in Spanish

Read this part, the rest is optional

In the United States and many other countries, laws require that we make sure that all Web content is accessible, or readable in some way, by people who have impaired vision or are blind, as well as those who have impaired hearing or are deaf. Regardless of regulations and company policies, it's simply fair to give everyone an equal opportunity to learn. But in addition to the satisfaction of knowing that you did the right thing, you'll benefit in several ways, too.

How this helps you

  • You will reach a wider audience, because more people will find it in searches.
  • Your article will be easier and faster to read, thus more people will actually read the entire article.
  • Your article will be more technically accurate, because copy editors without technical expertise won't end up writing part of the content.
  • Your article may be published sooner, because it will take less editing and production time if you follow these instructions.

The 3 things that you must do and not do

Remember this: Anything that the reader must know or do needs to be in text, too, not just in images.

  1. Include figures, captions, and Alt tags for all illustrations
    Write captions and Alternative Text (Alt) tags for every screen capture or illustration. Limit the Alt tags to 50 characters (copy editors can edit them for length, if necessary). There is a tag alternative, but using that isn't advisable for IBM® developerWorks® articles or tutorials.
    • Captions state what the image is or what it means in this context.
    • Alt tags need to describe what the image looks like or reveals for those who can't see the screen capture or illustration.
  2. Convey code to all readers
    Do not use screen output as an image for any code that readers must do something with or know about. Instead, insert the code as plain text so that everyone can read it.
  3. Use text colors and formatting that everyone can read
    Do not use red or green text or highlighting anywhere, because colorblind people cannot distinguish it from other text or elements.

Explanations of the 3 requirements for all Web content

HTML documents are accessible if they follow the IBM Web Accessibility Checklist. This checklist also applies to XML files that will be converted to HTML. Most of the information that follows in this section and throughout this article also applies to PowerPoint presentations and Word documents, whether the latter are published as such or converted to PDF files. Be sure to see the sections about each of those alternative formats for specific instructions.

1. Include numbers, captions, and Alt tags for all illustrations

All figures (images, graphs, and charts) must be numbered by continuing the sequence throughout the article, and they must have both captions and Alt tags. It is your responsibility, as the author, to provide them. If you do not include them, the copy editor writes them, thus you take your chances on what they say. Captions are in sentence case, meaning with an initial capital letter only, except for proper names. Identifiers and captions go above the image, both flush left, with a period after the figure number and no end punctuation, as Figure 1 shows.

Figure 1. The Create a Project dialog
Screen capture with values as described in text

See the Microsoft Word essentials topic for the easiest and best way to number your illustrations.

To ensure that the content of the images can be conveyed to blind or low-vision readers, you must provide meaningful text equivalents, known as alternative text or Alt text or tags. Screen reader software reads these aloud for visually impaired users. Alt text is not necessary for images that you use for visual effects only, such as an icon, but it is required for all illustrations or supplemental material that is essential or important for the reader to know and that you included to add meaning to your content. In XML, the completed figure tag in an IBM developerWorks article or tutorial looks something like this (put your cursor over the image to see the alt text):

<heading refname="figure2" type="figure"
alttoc="">Figure 2. Caption in sentence case except for proper names</heading>
<img src="figureFileName.jpg" width="315" height="146" 
alt="The workbench login screen"></img>

Alt tag descriptions should be less than 50 characters whenever possible (including spaces), because they will not pass the accessibility tests and audits otherwise. The developerWorks XML schema also specifies 50 characters, maximum. You can keep this handy in a text file to help write your Alt text descriptions.


If the description truly must be more than 50 characters, then you must use both the regular tag and the long-description tag. For XML, this includes the longdesc tag:

<heading refname="figure1" type="figure" alttoc="">Figure 1. Caption</heading>
<img src="figure1.jpg" width="315" height="146" 
alt="short description here" longdesc="long description here"</img>

However, an easier way to check the length is to search Help in your word processing software for character count, and just follow those instructions. In Microsoft Word 2007 and later, for example, you can then highlight the Alt text and click the first of two numbers next to Words at the bottom of your screen to check the character count (see the arrow at the bottom of Figure 2).

Figure 2. One way to check character count quickly and easily (Microsoft Word 2007)
character count in word

Do not repeat information that is in the caption. Instead, imagine that you're explaining the image to someone who is blind or has very low vision, and simply describe what it shows or means, succinctly.


Figure 1. Java code review Severity Summary illustrated by a pie chart
Alt: Warning = 835, Severe = 393, Recommendation = 246

Figure 2. Generate Java code
Alt: Screens show sequence: LAB7WebService > Generate

Figure 3. Welcome screen in Rational Product Name
Alt: Screen capture

For drafts in Word that will be converted to XML, simply put the Alt text after your caption. Be sure to flag it, though, like this:
Alt: Your text goes here

Also, so that screen reader users will have the same information as sighted users for complex graphs and charts, you may need to include additional descriptions in the surrounding text or perhaps link to the source document that you used to create the chart (as a side file for developerWorks content).


  • If you find yourself adding comment balloons to your images, you probably need to put that information in the text, instead, in a more thorough, clearer explanation that introduces the image.
  • It helps and saves time during production, thus gets your article published a bit sooner, if you include the source image files, preferably as JPGs or GIFs.

See Resources for a summary of the Section 508 standard of the U.S. Rehabilitation Act and a link to further information.

2. Convey code to all readers

Do not use code samples as images if the reader must use that code in some way or understand what it says to be able to follow instructions. You must write the code or the relevant parts of it in the text, too, because screen readers cannot decipher words, letters, and symbols in images.

However, you can use screen-output code when it is simply an example of results, rather than something that the reader must know about or use to follow instructions. In that case, add something like this as in the Alt tag: Example of code output.

IBM developerWorks articles and tutorials cannot use colored text in code, but you can use bold or italic text.

3. Use text colors and formatting that everyone can read

Use color as an enhancement, not as the only way to convey information (this applies to code, too). When color is the only way to differentiate information, some readers will not be able to understand the information. If completed items in a table are green and open items are red, they will look the same to someone who is colorblind and sound the same to someone who uses a screen reader. Provide another way of distinguishing the items. For example, add an X by completed items that are in green and an exclamation point by open items that are in red. If you use images of checkmarks, provide appropriate alternative text so that a screen reader can interpret them. Be sure to state in the text what the ! and X mean. Colored text may be prohibited by IBM in articles, tutorials, courses, and other Web content, but this is one way to explain the conventions that you're using, for example:

X = Complete (green), and ! = Open (red)

If you choose to use text formatting or colors to convey information for people with normal vision, also provide the information in other ways so that the information can be differentiated by colorblind, low- vision, or screen-reader users. Here is an example of describing screen text that is formatted for emphasis or in color:

The following list shows the latest status of inventory assets. Items slated for transfer appear in red, which is designated by <r>; items slated for sunset are underlined and designated by <u>; assets new to the inventory appear in italic, which is designated by <i> for this purpose.

Asset 1
Asset 2 <r>
Asset 3
Asset 4 <u>
Asset 5 <i>
Asset 6

Do not use color as clues in your instructions. People who are colorblind cannot distinguish red or green, and people who are blind cannot see any colors.

Incorrect: Click the red button.
Better: In the middle column, click the third button from the top, which is red.

Because some color combinations can make reading difficult even for sighted readers who are not colorblind, when creating documents, ensure that there is sufficient contrast between the page text and page background. Black text on a white background works well, but light gray text on a white background does not. In addition, avoid using patterned page backgrounds, because those can make differentiation between the text and background difficult for some people.

If your article contains colored text or objects, there is an easy way to verify that the information is not dependent on color: print or view the document in black and white. The information in black and white should be no less meaningful than a colorful version.

How to make your instructions accessible

As with images and other illustrations, we are required by law to make all essential information accessible to people with various kinds of disabilities. Laws in countries may vary, but IBM complies with United States laws.

Understand the nature of the problems and how people access your content

Start by reading the Web page about types of disability problems and ways people adapt.

It also helps to know about the various kinds of assistive technology that people with disabilities use:

  • Screen readers that use text-to-speech technology to read software to people who are blind
  • Screen magnifiers that enlarge information on the screen for people with low vision
  • Closed captioning displays for people who are deaf or hard of hearing
  • Special keyboards and input devices for people with limited hand use or mobility impairments

Therefore, your information may be conveyed in visual, auditory, tactile, or both visual and auditory form. Some users experience great difficulty in recognizing written words, yet understand extremely complex and sophisticated documents when the text is read aloud or when key processes and ideas are illustrated visually or interpreted as sign language. For some users, it is difficult to infer the meaning of a word or phrase from context, especially when the word or phrase is used in an unusual way or has been given a specialized meaning (such as jargon or slang). For these people, the ability to read and understand may depend on the availability of specific definitions or the expanded forms of acronyms or abbreviations.

Special tools, including speech-enabled and graphical applications, may be unable to present text correctly unless the language and direction of the text are identified. Even though these may be minor problems for most people, they can be enormous barriers for those with disabilities. In cases where meaning cannot be determined without pronunciation information (certain Japanese Kanji, for example), pronunciation information must be available, as well.

Explain in logical order: Where, then what

This is true in writing for any audience, but it is especially important for those who use assistive technology.

Incorrect: Right-click the UML operation in the Project Explorer, and select this item.
Correct: In the Project Explorer, right-click the UML operation and select. this item.

Related tip:
IBM Style uses American English. Therefore, say "the TypeName type" rather than "the type TypeName."

Tips for transferring text or images between Microsoft applications

Copying text or images from Microsoft Office XP or 2000 applications:

  • Text that is copied and pasted into PowerPoint creates text in the presentation. No additional changes are required for accessibility.
  • When images or charts are copied, the pasted information is an image.
    • Provide alternative text for the image.
    • If the image cannot be adequately described by using Alt text, provide a more detailed description in the surrounding text.
    Note: If alternative text was provided for the image in the original Office document, the alternative text will be copied into Word.
  • Formatting text
    • Use text formatting as an enhancement, but not as the only way to convey information. When you use formatting (for example, italics or bold) to convey information, it is inaccessible to someone who uses a screen reader. For example, if you create a table that displays APIs and format all new APIs in bold, there is no way for someone using a screen reader to differentiate new APIs, because bold type is the only way that the information is conveyed. To make it accessible, add another identifier, such as an asterisk.
    • Avoid using italic text, shadows, or outlines, because they make text difficult to read for someone with low vision. Choose a sans-serif font that is easier to read, such as Arial, Helvetica, Tahoma, or Verdana (the latter two are best for Web content).
  • Spell-check documents to avoid problems with screen readers mispronouncing words.
  • Do not use patterned backgrounds on pages or tables.
  • Provide sufficient contrast between text and the page background. For example, black text on a white background or yellow text on a black background work well.

Microsoft Word essentials

If you skipped Include numbers, captions, and alt tags for all illustrations, you need to read that part now to understand the context for these instructions.

Best way to number figures and insert captions

To number figures correctly and automatically, so that you don't lose track of the sequence, use this Word feature:

  • Insert > Reference > Caption (Figure 3). Watch each insertion carefully though, because if there is custom formatting in the file, Word occasionally functions erratically.
  • (Optional) To make the caption flush left, which is developerWorks style, change the default style from centered to flush left: Format > Styles and Formatting > Caption > Modify. If you have trouble with changing the default centered style to flush left, just leave it as-is. The most important thing is that the authors insert the numbering and the captions.
Figure 3. Insert automatically numbered figure captions
Drop-down menus with selections in Step 1

Use a period after the figure number, not a colon, and write the caption in sentence style, not title style. See the captions in this article for examples.

PDF file essentials

You need the full version of Adobe® Acrobat® (not just Reader) installed on your computer to convert Microsoft Office documents to accessible PDF.

Do not use Print > Adobe PDF to create the PDF file, because this creates an untagged PDF document that is not accessible

With your Word source file open, follow these steps to create a PDF file:

  1. Go to the Microsoft Office program menu, and select Adobe PDF > Convert to Adobe PDF.
  2. Select Save.
  3. Define the default language:
    1. Select File > Properties, and then select the Advanced tab.
    2. Select Language > English.
    3. Click OK.
  4. To create PDF documents that are both secure and accessible, enable these options in the Password Security > Setting dialog:
    1. Enable copying of text, images, and other content.
    2. Enable text access for screen reader devices for the visually impaired.

Then, be sure to check the accessibility settings in Acrobat. After you have converted the file to PDF, and from within the PDF file, check to make sure that it is set to apply accessibility tags:

  1. With your PDF open in Acrobat, select File > Properties.
  2. Under the Description tab, make sure that PDF tagged says Yes at the bottom.
  3. Change the setting to Yes if it says No.

Other PDF instructions from Microsoft

  • Convert untagged documents to tagged PDF:
    1. Open the document in Adobe Acrobat and press Ctrl+D to display Document Properties.
    2. Go to the Description section. If the Tagged PDF field says "No," the document is not tagged for accessibility.
    3. Close the Properties window.
    4. To convert untagged PDF documents to tagged PDF, select Advanced > Accessibility > Add tags to document.
  • Define the document structure.
    The logical structure defines the precise reading order of the document so it is accessible to assistive technology. Whenever possible, always add structure in the authoring application before converting to PDF. This means that you must use tags in the authoring tool to create elements such as headings, paragraphs, lists, and tables.
    1. For example, in Microsoft Word, define headings using the Heading tag rather than manually making the text bold and using a larger font.
    2. If the authoring application does not support tagged PDFs or if you are working with a legacy document that is not tagged, use the Add tags to document feature in Adobe Acrobat.
    This process will add structure, but it may require manual updates to correct problems such as incorrect reading order, missing alternative text, or missing table markup.
  • Add Alt text for important images.
    Images must have text alternatives so that they can be read by assistive technology.
    1. Whenever possible, add Alt text in the authoring tool before converting the document to PDF. Alternative text can be added by using Adobe Acrobat, but you will have to add the Alt text every time that the source document changes. Acrobat provides two fields for adding Alt text, but most document should use a short description for the image in the Alternative Text field.
    2. The process to add alternative text varies between Acrobat versions, so consult Adobe Acrobat Help for specific instructions.
  • Make links accessible. Some links in PDF documents may not be recognized by assistive technology. If you listen to the PDF document with a screen reader and no links are announced, use the Create Link tool in Adobe Acrobat Professional to identify and activate the links. Adobe also supports adding alternative text for links to make the link more descriptive to improve usability.
  • Convert scanned documents to accessible PDF. Scanned images are not accessible. See "Converting scans to accessible Adobe PDF content" in "Creating accessible PDF documents using Adobe Acrobat" for more information.

PDFs created with ID Workbench

PDF documents created with IDWB (ID Workbench) 3.8.2 may not be fully accessible. IDWB 3.8.2 supports some accessibility features, but does not support alternative text for images, accessible syntax diagrams or accessible tables. Alt text and table headings can be added manually using the Tags Palette. Syntax diagrams will not be accessible.

PowerPoint essentials

[From Microsoft] Follow these steps to create accessible Microsoft® PowerPoint® presentations:

Provide alternative text for all images. PowerPoint objects that require alternative text include clip art, objects, drawings, and auto shapes. Word Art is an image, but PowerPoint automatically adds the text that you type to the alternative text field for the image. When you create a diagram, the type of diagram (Pyramid Diagram, for example) is automatically added in the alternative text field. However, this is usually not a sufficient description, so you will need to modify that alternative text. To dd alternative text for each image:

  1. Select the image and select Format > Object or Format > Picture.
  2. When the dialog displays, select the Web tab.
  3. In the Alternative Text field, enter a text description of the image. The alternative text should effectively replace the image so that a sighted user and a blind user would get the same information from the image.

If the image is provided purely for visual effect and does not add to the meaning of the document, do not add alternative text. Leave the field blank.

Provide alternative text and a text description for charts and graphs

Under the Web tab of the Format Objects dialog, provide a summary in the Alternative Text field. If the summary does not include enough information to understand the chart, use one of the following techniques to provide additional information about the chart:

  • Provide a detailed text description in surrounding text. The description must convey the same information a sighted user sees.
  • Add additional information in the speaker notes. In the Alternative Text field, provide the short description and tell readers to check the speaker notes for more information
  • Add a link to the source content. For example, provide a link to the spreadsheet that generated the chart. The source document must also be accessible.

Group graphic objects into a single object

Some images are composites of many elements which makes the page difficult to read with a screen reader. For example, a background image of the world may represent each country as a separate graphic. This will cause a problem for anyone using a screen reader. To be accessible, the objects should be grouped as a single object. Use either of these two ways to group objects:

  • Use the PowerPoint Grouping option to group composite objects into a single object.
  • Select all objects in the group and press Shift+F10. Select Grouping > Group to group them into a single object.

Sometimes, grouping will still not result in a single object. In that case, you need to group the items and save them as a JPG file. This also results in a smaller presentation size. To convert a grouped object to a JPG file:

  1. Select all of the objects in the group.
  2. Highlight the group, select File > Save as, and then select *.jpg (where the asterisk is replaced with your new file name).
  3. Save the file.
  4. When the new images is inserted in the presentation, add appropriate Alt text.

Key policies and regulations

According to IBM: "Accessibility, as it pertains to information technology (IT), is about removing barriers that inhibit the access of certain groups, including people with disabilities, mature users, and non-native language learners."

U.S. federal

Section 508 of the United States Rehabilitation Act requires that when federal agencies develop, procure, maintain, or use electronic and information technology, they shall ensure that the technology allows [anyone] with disabilities to have access to and use of information and data that is comparable to that to [people] who are not individuals with disabilities, unless an undue burden would be imposed on the agency.

The Section 508 standard 1194.22 (a) for accessible alternative text lists examples (such as alt and longdesc tags) of how to provide text equivalents. These are the key points (from the Information Technology Technical Assistance and Training Center):

  • Text equivalents can be provided through a figure caption, content in the surrounding text that describes the image, or other methods. The key is to provide text for understanding any images that provide useful information to the user or reader.
  • Charts or tables must have an extended description that accurately conveys their content. Simply writing "chart showing results of data" is insufficient. The information conveyed needs to be accurately described, as succinctly as possible.
  • For complex images or other illustrations, you may need to include both a 3- to 5-word Alt tag and a longer description of 1-3 sentences (or more, if essential). This will enable screen reader users to access the longer description, but it does not require them to hear it every time that they return to the page.


W3C Web Content Accessibility Guidelines (WCAG)

Abstract excerpt: These guidelines explain how to make Web content accessible to people with disabilities. The guidelines are intended for all Web content developers (page authors and site designers) and for developers of authoring tools. The primary goal of these guidelines is to promote accessibility. However, following them will also make Web content more available to all users, whatever user agent they are using (for example: desktop browser, voice browser, mobile phone, automobile-based personal computer) or constraints they may be operating under (such as noisy surroundings, under- or over-illuminated rooms, or a hands-free environment). Following these guidelines will also help people find information on the Web more quickly. These guidelines do not discourage content developers from using images, video, and so forth but, rather, explain how to make multimedia content more accessible to a wide audience.

IBM corporate

IBM Corporate Instruction 162 (CI 162) requires that hardware, software, Web pages, services, and all internal applications and tools are accessible to Persons with Disabilities (PwD).

You must comply with these requirements:

  • Provide aids to navigation for screen reader users:
    • An embedded link that allows readers to skip navigation links to quickly get to the main content of the page
    • Proper markup for identifying the page title (for example, an <H1> tag or element)
  • Provide text equivalents for images and image map hot spots.
  • Provide null text equivalents on decorative images.
  • Identify row and column headers for data tables.
  • Programmatically associate labels with form fields.
  • Use valid XHTML 1.0 Transitional markup language.
  • Support browser settings for enlarging text and user style sheets.
  • Use consistent navigation mechanisms and style of presentation throughout the site.
  • Enable keyboard navigation of Web pages.
  • Identify the primary natural language of each page.
  • Test pages for compatibility with assistive technology if you use JavaScript for essential function of Web pages.
  • Include accessible HTML alternative versions of Flash content.



Get products and technologies

  • Download oXygen/ XML Editor and XSLT Debugger (for multiple platforms), which most developerWorks editors use, or Altova XMLSpy (for Windows).
  • To use the dw-transform.vbs script to transform your article or tutorial, you need the latest version of Microsoft's XML Parser (MSXML) This is the file that you need: msxml.msi.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Web content accessibility instructions for authors