Accessibility Guide

Introduction

Our membership is diverse, and we strive to support learning needs and preferences across a wide variety of content formats and devices. This guide is meant to help our content partners understand and take full advantage of accessibility features built into the platform and to point out best practices and key resources to create a better learning experience for the widest possible audience.

This guide relies heavily on the Web Content Accessibility Guidelines (WCAG) 2.1, published by the W3C. WCAG 2.1 aims to make web content more accessible by providing a shared set of technical guidelines, success criteria, and target conformance levels. Each of the guidelines falls under one of four guiding principles, which state that content on the web should be Perceivable, Operable, Understandable, and Robust. The conformance levels are A (essential for accessibility), AA (ideal), and AAA (specialized). We recommend working toward AA conformance.

Accessibility Features of the O’Reilly Learning Platform

The design system behind O’Reilly’s learning platform has been crafted with accessibility in mind, and our components leverage both inclusive design principles and WCAG 2.1 AA standards to benefit the broadest range of users. Each component uses semantic HTML markup under the hood, proper color contrast, are navigable by both the mouse and keyboard, and are reachable by screen readers.

In addition to providing content in a variety of modalities, we give our members tools to customize their own learning experience, such as the ability to control font size, color scheme, and other typographical preferences and support for video closed captioning, transcripts, and adjustable playback speeds.

Guidelines for Accessible Text

Accessible EPUB 3, by Matt Garrish, gives an excellent, quick introduction to how standard best practices applied to structure and metadata improves accessibility and usability for all. This short guide gives easy-to-follow advice on ensuring that your content’s structure and semantics are understandable by a wide variety of devices.

The following best-practices will help make your content accessible to a wide audience.

Use standard elements for the purposes they were made: understand and use the HTML5 spec. Using elements according to standard rules helps assistive devices “understand” what role the content is playing.
Avoid reliance on style, typography, or color for conveying meaning. Examples of what not to do include representing complex tables or code blocks as images. Doing so may preserve the exact look you hope to capture, but at the cost of providing a poor experience for some readers. Another example is using color or typeface alone to distinguish important semantic attributes, which can exclude a significant population from realizing the full potential of your product.
In addition to using standard markup elements, take care to conform to current markup best practices, which will aid accessibility tools that need to parse your content. As an example, from WCAG 2.1, Success Criterion 4.1.1 Parsing: In content implemented using markup languages, elements have complete start and end tags, elements are nested according to their specifications, elements do not contain duplicate attributes, and any IDs are unique, except where the specifications allow these features.
Consider how a user might “move” through your document using assistive technologies: are you giving them enough structure and semantics so they can understand what a section contains? Are you making your structure overly complex or too deeply nested? Does your structure give them clean ways to “skip” or “escape” from sections?
Sections and Headings. Use appropriate heading levels (<h1>, <h2>, <h3>, etc.). Help assistive devices navigate your content by using <section> elements.

Example:

<section data-type="chapter">
  <h1>Chapter Title</h1>
  <p>Your text goes here.</p>
  <section data-type="sect1">
    <h1>This Is a Top-Level Heading</h1>
      <p>Section text begins here.</p>
      <section data-type="sect2">
        <h2>This Is a Second-Level Heading</h2>
        <p>Your text goes here.</p>
        <section data-type="sect3">
          <h3>This Is a Third-Level Heading</h3>
          <p>Your text goes here.</p>
        </section>
      </section>
    </section>
  </section>
</section>

Lists. Use the appropriate container element for the type of list: <ol>, <ul>, or <dl>. Use <li>, <dt>, or <dd> as appropriate to identify list items and give readers a way to traverse or escape from them. Don’t add complex <span>, <class>, or <div> elements when they’re not necessary. They can do more harm than good for accessibility.

Examples:

<ol>
  <li>Text goes here.</li>
  <li>Text goes here.</li>
</ol>

<ul>
  <li>Text goes here>/li>
  <li>Text goes here>/li>
</ul>

<dl>
  <dt>Term goes here</dt>
  <dd>Definition goes here</dd>
  <dt>Term goes here</dt>
  <dd>Definition goes here</dd>
</dl>

Tables. Complex tables can be challenging for assistive technologies. The W3C provides this guide to mark up tables. In general, avoid using purely visual techniques to structure your tables. As much as possible, use the <table>, <tr>, <th>, and <td> elements to define the structure of your data. DON’T set tables as images.

Example:

<table border="1">
  <caption>Features supported by Hadoop release series</caption>
  <thead>
    <tr>
      <td>Feature</td>
      <td>1.x</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Secure authentication</td>
      <td>Yes</td>
    </tr>
    <tr>
      <td>Old configuration names</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

Sidebars. Help assistive technologies identify sidebar content by using the <aside> element.

Example:

<aside data-type="sidebar">
  <h5>Sidebar Title</h5>
    <p>Here's a sidebar. Sidebars are great for setting aside a section of text that is related to the surrounding content but that doesn't necessarily fit into the main flow.</p>
</aside>

Figures. Use <figure> and <figcaption> elements and provide good alt-text descriptions. Provide meaningful alt-text descriptions for images, but only if the image is meaningful. If an image is purely stylistic, without any real meaning, don’t provide an alt-text description. (More guidance on writing alt-text can be found here.) DON’T use figure markup for text content, such as code blocks or tables.

Example:

<figure>
  <img alt="Drawing of Tarsiers" src="images/tarsier.png" />
  <figcaption>Figures caption goes here.</figcaption>
</figure>

Code blocks. Use the <pre> element to mark up code examples. DON’T set code as an image.

Examples:
Here is an informal code listing.

<pre data-code-language="python" data-type="programlisting">
  print('hello world')
</pre>

And this is a formal listing, or example.

<div data-type="example">
  <h5>Hello World in Python</h5>
  <pre data-code-language="python" data-type="programlisting">
    print "Hello World"
  </pre>
</div>

Guidelines for Accessible Video

Our video player provides support for closed captioning, transcripts, and allows the user to control playback speeds—all features designed to make video content available to a wide population of our members. Please consider the following best practices when creating video content with accessibility in mind.

Captions and transcripts provide useful tools to a wide variety of users, in many different situations and with widely varying accessibility needs. We support captions in SRT or DFXP format: in addition to making your content accessible to a wider audience, you’ll increase your SEO on our platform by allowing full-text search. Read Providing an alternative for time-based media for video-only content, from WCAG 2.1 to learn more. Our platform uses these standard caption formats to create a transcript of the video content.
Include audio description, if needed. This ensures that all meaningful but non-spoken content is captured in the captions and transcripts.
Avoid flashes, which may trigger seizures in some viewers: See further discussion in Three Flashes or Below Threshold, from WCAG 2.1