About this guide

This guide covers the principles and processes for creating accessible document content and structure, evaluating the accessibility of documents, and remediating accessibility issues in documents.

Accessibility at Red Hat

Red Hat’s culture is built on the open source principles of transparency, collaboration, and inclusion. As content developers, with the knowledge that so many people access our sites and use our documentation to learn about and use our products, we must consider the diversity of our users when building that content. Accessible content creates a better experience for more people.

There are many groups at Red Hat that are involved in the design of accessible technology, delivery of accessible content, and growing a workforce and marketplace that values accessibility. The CCS Accessibility Workgroup (CCSA11y) has been established to interpret accessibility guidance for CCS and support writers with guidelines and practical advice about how to craft accessible documentation for an accessible product.

Additional resources

Getting help with accessibility

Red Hat has a small group of volunteers that are a part of Red Hat’s accessibility initiative. Their members are eager to help and support you with accessibility compliance. Contact the CCSA11y team for help with specific needs related to providing accessible content at Red Hat. CCSA11y can provide the following assistance:

  • Guidance in evaluating your content for accessibility.

  • Open office hours to help individuals and groups improve their content accessibility.

  • Recommendations for testing software and accessibility technology products.

Creating accessible documents

Document accessibility is the practice of making documents usable by all people, regardless of ability, using the technology of their choice. Use this section to learn about and implement accessibility best practices in your writing.

Making document structure accessible

When creating accessible content, think in terms of structure first. Poor structure reduces the quality and usability of our documents. Documents with good structure are easy to read and easy to navigate. Documents with poor structure are tedious to navigate and difficult to read. Documents created without consideration of accessibility can also result in entire sections of the document to be unavailable to a person using a screen reader. To make the content easily understandable to anyone, you can rely on Red Hat’s minimalism principles:

  • Clear, concise paragraphs to make information accessible to more users.

  • Headings to convey structure, organization and content of the document.

  • Bullet lists to simplify and convey the most essential pieces of information.

Developing documentation that is structurally accessible allows users to quickly focus their attention on your key points. And, screen readers can also easily navigate through your content, moving from section to section in a logical flow.

Like all other accessibility guidelines, good content structuring raises usability for everyone, because everyone appreciates and quickly grasps well-structured content.

Making content accessible

Some aspects of web accessibility are of a technical nature, and they are handled by the Digital Experience (DX) team. The DX team takes care of fonts and colors, contrast ratios, creating form labels, providing keyboard accessibility, and so on. They are responsible for the framework of our online documentation.

We, however, are responsible for making our documentation content accessible. When creating content, there are a number of guidelines to follow to ensure your content is accessible:

  • Use clear and simple language.

  • Make all information available in text form. This means providing alternative text for images and links, providing descriptions of charts or graphs, and providing descriptions for instances of color, size, or shape-based information.

  • Use correct asciidoc attributes and avoid getting creative with formatting.

  • Do not skip heading levels or use simple bold formatting for headings.

  • Table structure should be kept simple.

  • Do not use color or spatial position to convey information.

When you incorporate accessibility into your process, the result is stronger content for everyone.

Headings

Headings play a key role in the accessibility of any document. They are essential for navigating and finding information quickly. They are used for navigation by screen reader users and they provide a clear structure of the document, making it easier to scan through the content. To ensure the accessibility of your documents, headings should:

  • Be created using proper asciidoc tagging.

  • Convey a clear and accurate structural outline of the sections of content.

  • Accurately describe the content.

  • Not skip hierarchical levels.

Images

Making images accessible is fundamental for accessibility compliance. All images must have a meaningful text alternative that serves the equivalent purpose of the image. The content of the alt text will vary based on the purpose of the image. The alt text should typically:

  • Be accurate and equivalent in presenting the same content and function of the image.

  • Be succinct. This means the correct content (if there is content) and function (if there is a function) of the image should be presented as succinctly as is appropriate. Typically, no more than a few words are necessary, though, rarely, a short sentence or two may be appropriate.

  • Give blind users a functional equivalent or substitute for the image.

  • Convey the purpose of the image — why you put the image in the document — rather than just the purely visual irrelevant aspects of the image. Include any text which happens to be in the image.

  • NOT be redundant or provide the same information as text within the context of the image.

  • NOT use the phrases "image of …​" or "graphic of …​" to describe the image. It is usually apparent to the user that it is an image. And if the image is conveying content, it is typically not necessary that the user know that it is an image that is conveying the content, as opposed to text. If the fact that an image is a photograph or illustration, etc. is important content, it may be useful to include this in alternative text.

Screen readers announce links, and then read the link text. You don’t need to do anything special to make that happen.

Screen reader users frequently navigate by links. Therefore, the link text should make sense when read out of context. Screen reader users often navigate from link to link by using the tab key (or shift + tab to go backwards through links). When navigating this way, only the link is read, not the rest of the sentence, so ambiguous links like "click here" or "more" are not helpful. Links like "products" or "contact us" are more useful.

  • Links Must Contain Text: Links should not be empty. Screen readers may end up reading the link destination or some other piece of information (such as an image file name, if the only thing in a link is an image without alt text) if there is no text in the link. Sometimes that other information is helpful, but often it is not. It is better to provide meaningful text in the link.

  • Links Must Accurately Convey the Link Destination: Ensure link text (and alternate text for images, when used as links) describes the destination or purpose of the link. If possible, the link text should make sense out of context of the words around it.

Visual aspects

While it is acceptable to use visual styling in documentation, you should not rely on visual aspects of your content to convey meaning. Be cautious of referencing size, location, position, shape, or sound in information because they rely on a specific sense that some users may not have. For example, you should avoid:

  • Instructions like “to the right,” “to the left,”. Screen readers follow content in a linear fashion, reading it from top to bottom, so there is no “left” or “right” in that context.

  • Using color as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element. A text alternative that screen readers can speak out loud should always be included.

  • Using spacial relationships like "the larger area" "the smaller area" to describe information. This relies on vision and the ability to perceive spatial relationships.

Instead, you should modify the instructions so that specific senses are not necessary to understand the information.

Tables

Tables can be very useful in presenting meaningful data. However, they are a challenge to people who cannot visually perceive the relationships between the cells and their contents. There are a number of limitations to consider when creating accessible tables.

  • Tables with a complex structure, where cells are merged or there are multiple levels of headers for any given dimension, should be avoided. Where possible, an easier option would be to plan your data presentation in such a way that you can break a complex table into a series of simpler tables. These tables will also be more usable for the general audience.

  • Nested data tables are data tables which exist inside other data tables. Nested data tables break the accessibility of the data presentation as a whole, making it impossible to associate the data and header cells correctly.

Accessibility testing

Accessibility testing helps find issues or barriers that users with disabilities might run into while using our content. The issues found during testing give us the opportunity to make improvements to the overall user experience with the product documentation.

Automated testing

Automated testing focuses on finding accessibility issues, quickly and consistently, using an accessibility browser extension or integrated testing module. This is the quickest way to find accessibility issues in your content.

Tip

After testing several browser extensions, the CCSA11y Team recommends the IBM Equal Access Accessibility Checker browser extension if you need to test a page for accessibility. However, this is for general accessibility testing on a local build of your document. If you test a page on the customer portal, you will get results from the entire framework rather than just from the content you’ve written.

Use the Accessibility Assessment option of the Accessibility Checker and set it to report results sorted by requirement rather than element role or rule. The IBM accessibility requirements and automated tools are numbered and aligned to the international standards, so it makes gathering and recording the results simple.

Violations

If Violations appear during this first verification step, we recommend stopping the verify process. Return the product to development for remediation.

Needs Review

If Needs Review issues appear during this first verification step, we recommend pausing the verify process. Ensure that these have already been resolved or return the product to development for remediation.

It is counterproductive to continue to manual testing until the automated tool produces a report free of Violations or issues that Need Review. After the automated test returns a clean result, you can move on to manual tests.

Note

Automated tests only cover a subset of the overall accessibility requirements. Therefore, automated tests must be followed by manual tests and screen reader tests to verify that all the applicable requirements have been met.
Additional resources

Testing accessibility with a manual inspection

Manual accessibility testing uses keyboard, visual, and content tests to find issues that automated testing cannot.

Manual testing is divided into steps. A visual inspection is followed by pointer and keyboard checks. Testers then validate the ability of the content to resize. They complete manual testing by confirming the accessibility of interactions.

Prerequisites

  • An automated report free of Violations or issues that Need Review

Procedure

  1. Navigate through your document using a keyboard and ensure the following:

    • Tabbing order logical and intuitive

    • Keyboard focus indicator is visible

    • Pressing Enter or Space bar selects a specific item

    • There are no keyboard traps

      Note

      A common problem is keyboard focus getting caught in controls and being unable to get out.

  2. Scan through the document and verify the contents against the Accessibility checklist.

After testing is complete, violations should be reported such that they allow even those with little or no accessibility knowledge to fix the issue. Violations should be explained and guidance for remediation should be provided when possible.

Screen reader testing

Testers use a screen reader to confirm that the experience parallels the results from manual testing and is equivalent to the intended design. This step ensures that the visual information on the screen is reinforced programmatically.

Screen readers are designed primarily for blind users, so there no need for a user interface. You turn a screen reader on, and it starts reading the content currently in focus.

Screen readers can be disorienting for sighted users at first, but with practice, you can get used to it.

Using a screen reader requires you to use basic keyboard shortcuts. Each screen reader has a different set of keyboard shortcuts, and the list of all available keystrokes is extensive; however, you can typically get by with just a handful of shortcuts.

The best way to learn how to use them is to pick one and learn the basic controls.

Additional resources

CCSA11y recommended tools for accessibility testing

The range of capabilities of automated testing tools is broad. Basic tools can test one page at a time using a defined set of rules. Basic automated testing tools can be extensions or add-ons to a specific browser, while others are browser-independent.

Automated accessibility checkers

After testing several browser extensions, the CCSA11y Team recommends the IBM Equal Access Accessibility Checker browser extension if you need to test a page for accessibility. However, this is for general accessibility testing on a local build of your document. If you test a page on the customer portal, you will get results from the entire framework rather than just from the content you’ve written.

Note

Automated tests will not catch all issues. Complete your accessibility assessment with a quick unit test for accessibility or follow the full accessibility test process.
Screen readers

There are a number of different screen readers available including the following:

CONCISE Accessibility checklist

Use the concise accessibility checklist as a quick reference to improve the accessibility of Red Hat product documentation.

Table 1. Concise accessibility checklist
Check for Checked

Images and Alternative Text

  • Icons, images, diagrams, and non text elements have a meaningful alternative-text description.

    • Icons - alt text describes what the icon does (not what the icon looks like)

  • Complex images such as charts, workflows, and graphs have descriptive text near the image.

  • The document does not contain images of text, for example, a screen capture image of an informational table.

☐

Links and Hypertext

  • URLs and cross-reference links have descriptive text that conveys information about the content of the linked target.

  • URLs are linked to correct and valid Web destinations.

☐

Tables

  • Tables have a simple, logical reading order from left to right, and top to bottom. Examples in the W3 accessibility guidelines.

  • Tables include a header row.

  • Avoid empty or blank table cells.

  • Header cells utilize the th tag and data cells utilize the td tag.

  • Tables are labeled with a caption.

☐

Colors and other visual information

  • Avoid instructions that rely solely on sensory characteristics. For example, do not use “Click the square, blue button to continue.”

  • Information is conveyed by methods and not by color alone.

  • There is sufficient contrast between foreground and background text or graphical elements in images and diagrams.

  • Instructions for navigating through an interface make sense without directional indicators such as left, right, above, and below.

☐

Well-formed HTML and Meaningful Document Sequence

  • Headings are correctly nested from H1 to H2, H3, and so forth, without skipping heading levels.

  • The correct Asciidoc tags are used to produce the intended HTML code.

☐