Learning Content Accessibility Guidelines

Overview

GitLab is committed to compliance with all applicable laws and regulations, including, the Americans with Disabilities Act of 1990. We believe that our Diversity, Inclusion, and Belonging value provides the foundation for our commitment to create an environment that enables everyone to contribute to and co-create the software that powers our world. To support these beliefs and commitments, GitLab encourages team members to make learning and development experiences as accessible as possible to the entire GitLab community. In order to facilitate this, GitLab aims to conform to level AA of the World Wide Web Consortium (“W3C”) Web Content Accessibility Guidelines (“WCAG”) 2.2, which is the most widely accepted set of recommendations for making web content more accessible.

GitLab’s Ethics and Compliance Program and the Accessibility Working Group have collaborated to create the following guidelines to help GitLab team members create accessible web learning experiences (whether internal or external) training platforms used by GitLab, in keeping with the WCAG recommendations. To do this, the guidelines outline the different types of content you are likely to use or design, the potential challenges that each can create for your user, and what you can do to prevent or mitigate those challenges.

These guidelines are meant to be a starting point but throughout the guidelines links are provided to additional resources so that you can explore the WCAG recommendations in more detail and achieve a deeper understanding of what compliance may entail. Any questions about these guidelines or the compliance that it promotes may be directed to The Ethics and Compliance team via the #ethics_compliance Slack channel. Separately, please refer to the GitLab Content Style Guide for guidance on brand voice, tone, grammar, and punctuation. Any questions about the Content Style Guide may be directed to the Marketing team via the #brand Slack channel.

An accessible experience

What does it mean to provide a more accessible learning experience? Simply put, this means that no user’s access to content and functionality is limited in any consequential way. This may involve making content available in multiple forms and may involve considering the different ways that users consume and interact with course content.

Platform

Before we discuss content, let’s talk about learning and development platforms. A learning and development platform is the delivery method for course materials and contains the functionality to navigate, read, watch, and interact with the content. A platform that isn’t accessible or lacks certain features is going to create a barrier to some users and may prevent them from fully engaging with the course or absorbing the information that it is meant to convey.

GitLab’s primary learning management system, LevelUp (referred to as “GitLab University” externally), is from Thought Industries. Before you consider using a different learning and development platform, do some research to understand whether that platform provides an accessible learning experience. Many companies will also provide an accessibility statement of compliance that outlines their intentions and ways to remedy issues. Some even go further by providing a Voluntary Product Accessibility Template (VPAT®) that explains how the related technology satisfies accessibility requirements.

Plain language

Communicating, in written or verbal form, in plain language, can be an important element of an accessible experience. Consistent use of plain language benefits every form of media and all users.

From plainlanguage.gov:

Plain language (also called plain writing or plain English) is communication your audience can understand the first time they read or hear it.

Considerations

People absorb information differently, so we must recognize that language that is plain to one set of readers may not be plain to others. We can, however, consider the following themes and attributes that are common to plain language:

  • The language is familiar to all users and written at an appropriate comprehension level;
  • Explanations or definitions are provided for technical terms, unusual words, or abbreviations;
  • Content is edited to address grammar and spelling errors;
  • Headings follow a logical order (using heading levels 1–6) to create a scannable and structured outline for sighted and screen reader users;
  • Headings clearly communicate what users can expect in the section that proceeds; and
  • Calls to action are clear and unambiguous. For example, “Discover more about pipelines“ instead of “Read more“.

Written material is in plain language if your audience can:

  • Find what they need;
  • Understand what they find; and
  • Use what they find to meet their needs.

Guidelines

While much of the success criteria from WCAG 2.2 applies to content in some form, the following are most related to the concept of plain language and the presentation of text:

Images

A text alternative for images is important for conveying non-text content to a user who may not be able to see or understand the image for any variety of reasons. There are three types of images; simple, complex, and decorative.

Simple Images

A simple image is one that can be described in a few words or a short sentence. Examples might include a product screenshot or a photograph of people having a conversation. Simple images are most commonly described with “alt text,” which gets its name from the alt image attribute in code. Alt text looks like this: <img alt=“text alternative”>. The “text alternative” describes the image in a text-based format that screen readers can read out loud, which helps the user understand what the image is meant to convey. Writing the text alternative can be challenging and sometimes subjective. Compare the following examples to understand how to make alt text more descriptive:

  • Poorly-written alt text: <img src="team.jpg" alt="image">
  • Well-written alt text: <img src="team.jpg" alt="Four team members discussing a project around a conference table.">

In both examples, the alt text alerts the user to the use of an image but the first does not describe the image, while the second describes what the image is meant to convey (“four team members discussing a project … “). Here is another example:

  • Poorly-written alt text: <img src=”dog.jpg” alt=”dog”>
  • Well-written alt text: <img src=”dog.jpg” alt=”My golden retriever dog, Scully, posing for a photo in the living room”>

Both examples mention a “dog” but the poorly-written alt text does not describe the dog in any way, while the well-written alt text describes the dog in enough detail to provide the user helpful context. Read this Alternate Text guide from WebAIM to learn more about how to craft meaningful alt text.

Complex images

A complex image is a visual that is more informational in nature and requires more than just a simple explanation. Examples might include a flow chart or data visualization. Similar to a simple image, a complex image requires alt text, which serves as a brief description, but also a long description that explains, in more detail and using more text (aka “long text”), the essential information contained in the image. If the complex image consists of data, consider using a text table of the data rather than long-form text. Learn more about the W3C’s long description methods here.

Data visualization, which is the graphical representation of information and data, should use colors with sufficient contrast and labels within the chart, so that the user does not have to rely solely on color to understand what is being conveyed. Look at the data visualization color palette documented in the Pajamas Design System for GitLab or read An Accessibility-First Approach To Chart Visual Design, by Kent Eisenhuth and Kai Chang, to understand other ways to consider data visualization while creating accessible learning experiences.

Decorative images

A decorative image has no meaningful content value and doesn’t need to be announced by a screen reader. Examples might include background patterns or an icon that is used as a visual anchor. Use an empty alt attribute for decorative images so that they are not unnecessarily announced.

Considerations

  • All images should have an alt attribute, even if the alt attribute is empty (alt=””).
  • Use longer text and/or tables to describe complex images.
  • Leverage high-contrast colors, labels, and other data visualization techniques, when visualizing data.
  • Try to avoid text within an image, but if present, make sure it’s also available in plain text, which is text consisting of characters without special formatting.
  • Avoid using animated GIFs since a user can’t control the playback.

Guidelines

The following success criteria from WCAG 2.2 apply to images:

Video and audio

Video and audio recordings should have an alternate way to obtain the content. This allows a user who is hard of hearing or deaf to read the content using captions or text transcript while a user who is visually impaired may use a screen reader or other assistive technology.

Captions

Captions are the text version of spoken audio and sounds and should be provided for all videos, when possible. Closed captions can be turned on and off by the user, where open captions are always present. There is no size requirement for captions (sometimes they will scale with the player), but they must be readable and have sufficient contrast. A caption benefits someone who can see the video, but either by impairment or choice can’t use the audio. If using automated captioning, review them to ensure they accurately reflect the spoken content; especially for technical terms like ‘DevSecOps’ or Kubernetes.’

Audio descriptions

Audio descriptions provide information about visual elements in a video. For example, describing the scene, actions and gestures, or expressions. They are announced between dialogue. Watch an example. An audio description benefits someone who can listen to the video audio, but either by impairment or choice can’t use the video.

Transcripts

A text transcript should be provided for audio-only media and prerecorded video. The transcript can be included on the same page, linked to, or available as an accessible document. A transcript benefits a variety of users, from those who prefer to read, to those who obtain the text content through a screen reader or other assistive technology.

Text and data visualization

Since both text and data visualization (charts) are essentially embedded in a video with no way for a user to control their appearance, ensuring they are clear and discernable at the outset is key. Discernable means text or data visualization that can be seen, perceived, and understood by users.

Text should have sufficient contrast against the background. If it’s meaningful content, the text content should also be included in the audio track.

Charts in videos should utilize patterns and textures ( such as lines, dots, or crosshatching) instead of relying solely on color. Here, as an example, is a chart that uses patterns and textures:

Data-Visualization-Example

This helps viewers distinguish different segments or lines in a chart, even if they cannot differentiate the colors. During the video, consider highlighting or enlarging specific areas of the chart when discussing them to focus attention and help all viewers, particularly those who might struggle with smaller, detailed graphics. Provide a verbal description of the key elements of the chart as they appear in the video. This description should accompany the visual display, explaining what is being shown, including any patterns or textures used.

Considerations

  • A text alternative should always be provided for audio and video media.
  • Do not autoplay video or audio content. Doing so can be confusing if a screen reader is also making announcements.
  • Captions and transcripts should accurately reflect the original content.
  • Use tools like the WebAIM Contrast Checker to ensure sufficient contrasting colors for text and graphics in video.
  • When using charts, use patterns and labels along with colors to convey information.
  • Avoid flashing content, which is content that flashes or blinks rapidly.

Guidelines

The following success criteria from WCAG 2.2 apply to images:

Interactive content

If content is interactive (separately from the learning management system controls), ensure that all actions and content can be accomplished using a keyboard alone. Examples might include elements that flip to reveal information or that open embedded windows with more content. Many assistive technologies emulate keyboard behavior, so ensuring that all interactions can be done with a keyboard is critical for a wide variety of users who take advantage of a wide variety of input methods.

Considerations

  • All content and interaction should be able to be done with only a keyboard.
  • There should be no keyboard traps that a user can’t get out of, which happens when a keyboard user can’t move focus away from an interactive element.
  • Focus order (the order that a keyboard traverses interactive elements) should match visible reading order.
  • When an element has focus, there must be a visible focus indicator, which is a visual marker that shows which interactive element on a web page is currently focused and ready for user input.
  • Elements that can receive focus can’t be obscured by other elements.

Guidelines

Summary

Web accessibility is becoming increasingly important as more and more business, learning, and communication takes place online. Accessibility is especially important for GitLab and its mission, as universal access to information (especially learning content) helps ensure that everyone can contribute. When we start by considering accessibility, we are also more likely to deliver a more inclusive and engaging experience for all users.

By doing a bit of learning ourselves, we hope that GitLab and its team members will be better prepared to consider the various ways that people consume the information we provide, and whether or not we’re creating the best experience possible. In addition to these guidelines, which should be used by team members to create more accessible learning experiences, we also encourage team members to explore the links provided throughout this document in order to better understand and comply with the underlying WCAG guidelines.

Last modified November 1, 2024: Remove trailing spaces (6f6d0996)
View page source - Edit this page - please contribute. Creative Commons License