If you’ve made it to this guide in the first place, accessibility may be familiar to you already. Ultimately, the goal is to build an equitable world for disabled and able people; for documentation, this starts by making sure that disabled people can benefit from your documentation the same ways that abled people can whether they are blind or visually impaired, have limited mobility, are deaf or hard of hearing, or have mental disabilities.
This is a wide net to cast. Not only is there a breadth of experience and acommodations needed for all disabilities, the things that help one disabled person are often the exact things that would be impossible to use for another. So how in the world is accessible documentation even possible?
When in doubt:
Write it out. Text is one of the most flexible and adaptable methods of communication digitally. It can be read visually, audibly, haptically, and be translated to other forms with the right technology. (Note, this does not apply to images of text.)
Provide multiple options. Instead of having only text or only images to explain a concept, have both. This allows people to engage as they need, it provides multiple paths instead of a single path that can become a wall depending on someone’s ability.
Use things as they are intended. For example, if you are writing documentation in plain HTML, use HTML elements as they are intended (often called semantic HTML); use <button> for buttons, not links (<a>). This means that the accessibility support built into the structure you are working with can be leveraged, and there is much more accessibility support for many major structures than you may expect.
Listen to feedback. Each person can only know so much and the people using your documentation can provide great insight. Listening to feedback is not the same as immediately making changes as soon as they are requested, do examine the impact of options as best you can.
As a documentation author, it’s important to understand what is in your control and how you can make the most of it. This guide addresses only what is in control of documentation authors.
Authors make
Authors don’t make
✅ Documentation text
❌ Website theme
✅ Images
❌ The software being documented
✅ Videos
❌ Website dependencies
✅ Demos of other kinds
❌ The software used to access documentation
✅ Resource files for downloading
❌ External links
✅ Community support events
Note: Lots of people who write documentation do a lot of other things for the project as well. Because this guide cannot cover all possible accessibility efforts related to documentation at once, it only covers tasks related to this definition of documentation author.
The things authors can control are the things it is important to take responsibility for. The things authors cannot control are worthy targets for advocating that those who can change them make those changes with accessibility considerations.
Orienting oneself in the documentation is key to getting questions answered, discovering what options are available, or just plain knowing where to go next. Without intentional structure, any task on a documentation site gains extra obstacles.
The most important parts of documentation structure are to be consistent and to use the structural elements you have available to you as intended. Even if there are other issues, users have the best luck finding workarounds with consistent structure and predictable page elements.
Have descriptive, consistent titles for web pages.
Make sure page titles and their name in the navigation match.
Provide a table of contents or a summary of what someone can find on that page. Bonus points if they are links that allow you to jump to other headings on the page.
Use paragraphs, lists, and other or organization where appropriate. A wall of unbroken text does not work better.
Provide a site map, or a list of all pages on the documentation. This is usually available in or via the website footer.
Provide a search built in to the documentation. This is often available in the documentation site theme.
Writing accessible documentation text includes all the usual text writing considerations. Begin by following your project’s style guide and update it to include the following as needed.
Use proper grammar and punctuation for the language you are writing in. Write in complete sentences. It seems simple, but it makes a difference even from an accessibility perspective.
Use plain language. Plain language is less formal, direct writing that focuses on using words familiar to the audience where field-specific terms are not required.
Avoid using jargon. Many fields will have specific terms and these should be used and defined, but do not use jargon where a more common term will be more clear.
Where possible, include or link to a glossary of terms relevant in the documentation.
Use the full version of acronyms the first time they are listed so that readers have at least once reference point for the context of acronyms elsewhere in the documentation. Linking acronyms to their definitions may also be helpful.
Write descriptive link text. This means that someone should be able to tell where a link will take them before they click on the link text. For example, “visit Scientific Python” makes it clearer where the link points to than “click here.”
Contrary to text, images can be some of the least flexible types of media for people to interact with. At the same time, for people who can view them, images can be some of the most useful tools in explaining information, providing examples, and offering a quick reference.
There are two groups of accessibility considerations relevant to making images: considerations within the image and considerations surrounding the image.
Within the image, or the choices one faces when designing and making the image, authors have to consider the many different ways someone can see. Consider the following:
All images need to communicate clearly even in black and white. They can be color images, but they need to be readable and understandable if color is stripped away.
Be cautious of using colors that all have the same value, or amount of light or dark. When color is hard to distinguish or not available, colors of the same value will look the same.
Make sure details like text or annotations are large enough in context. There is not a single right answer on what large enough means, but keeping them no smaller than the smallest text on your documentation page when rendered is a good place to start.
Make sure the image can be expanded, zoomed, or otherwise respond to user size adjustments. This may cross into limitations with the documentation theme, but it is worth reviewing for and making a note if it is not within author control.
Do not use flashing animations for any animated images. Flashing refers to any fast, high contrast color and/or light changes more than three times per second. These are known to trigger seizures and other pain.
Be consistent with your visuals, iconography, and colors where relevant. This preserves continuity and can help users orient themselves within the documentation.
Consider if some information-dense images can be broken into multiple images.
Surrounding the image, or the choices one faces once the images appears in context, authors have to consider what happens if the image is not available.
Any text in the image needs to be available as actual text outside the image. No text should be lost because an image cannot be read.
Images need an image description (also called alt text or text alternatives). Generally, this is intended to capture the information the image provides in non-image form. Depending on the type of image and its role in documentation, there may be a few ways to do this. Refer to this image description decision tree).
For images with data involved, link out to the source data or a tutorial notebook when possible.
Captions are not image descriptions. Do not use one in place of the other.
In general do not use images to replace text information, use them to augment it.
Introduce videos and their relevance to the surrounding documentation directly before they appear.
Videos in documentation should not autoplay. They need a play button and a pause/stop button.
Videos with sound benefit from volume controls. Since this may be managed by the user outside the website, it is less critical.
Ideally, all videos with voices have closed captioning (text overlaid on the video player in time with speaking) and a transcript (text in paragraphs not timed to the video) linked. If this information is already in paragraphs surrounding the video, these may not be needed.
Videos are a good addition to documentation that can be very helpful for anyone wanting to see the software in action, but they are best used as additional documentation features. A good way to test that you’ve covered the same information elsewhere in the documentation is to break the link to the video and ensure that no information is missing.
While it is important to recognize what accessibility considerations are directly in the hands of those writing documentation, that doesn’t mean that a documentation author’s power has to end there. Even without taking on other documentation team roles, authors can impact choices and give feedback on the projects they work on.
Select for accessibility. Whether making documentation from scratch or writing for existing documentation, choices will always have to be made. Authors can select options to those choices that have accessibility in mind. Examples include
Choosing a website theme that has accessibility information included or has traits that fit WCAG or other standards.
Deciding to not accept new images to the documentation if they don’t have text descriptions.
Removing the need for dependencies that don’t have accessibility considerations from within the documentation, such as removing videos until you can link to a video player that does not autoplay.
Advocate for change. In many cases, accessiblity-related changes cannot be made by one person or require multiple people’s expertise. These situations benefit from advocacy, where an author can use the accessibility awareness they have to encourage others to make changes with them. Examples include
Noting accessibility issues you find in your own documentation by describing its current behavior compared with the desired behavior.
Asking specific questions about accessibility support to members of your team or to dependencies’ teams. Noting the desired accessible behavior is also helpful here.
Gathering with other people in your project or across others who want to prioritize accessibility efforts. Figure out what issues you can face together or what you want to advocate for as a team.
Edit what you have. Sometimes authors do have the option to make a direct change to an aspect of the documentation outside of its contents. When these changes are possible, they are often worth pursuing as long as the whole team is on board, though keeping in mind necessary maintenance must be done. Examples include
Updating the existing documentation to include descriptive links or make page titles match their navigation names.
Add specific accessibility considerations you feel comfortable reviewing for as a required part of the review process in accepting additions to the documentation. This could be declining to merge any documentation without in-order heading levels or that change the color of the theme to be low contrast.
Make changes to documentation dependencies like theme and contribute them upstream so the original project and all those using it can benefit.