How to Create Accessible Documentation

A metallic key sits on a blue ACCESS button on a computer keyboard.

There’s no point documenting our software if people can’t access the resulting information. That’s why we should be careful to always create accessible documentation.

I have a few friends with disabilities, and at one point or another, nearly all have expressed frustration with a website or piece of documentation that didn’t take their relatively simple needs into consideration. A number of disabilities can affect the way people interact with your documentation, including vision and hearing impairments, ADHD, dyslexia, auditory processing disorders, and visual perceptual issues.

Reading Ease

There are a number of things you can do to make a written article easier to read:

  • Get to the point. It’s easy to get the idea that good documentation reads like a pompous airbag. No; that’s bad documentation.
  • Use active voice. Occasionally this isn’t appropriate, but usually it is. Say “Press the Start button to begin,” not “To begin the process, the Start button should be pressed.” Active voice is more succinct and provides clearer instructions.
  • Break it into sub-headings. This helps people to skim-read until they find the bit of information they’re interested in. You can also link to these sub-headings at the start of the article or at the side.
  • Short paragraphs. Each paragraph should deal with a single topic. If you’re changing topic, change paragraphs too.
  • Use different formats. You’ll note that in this article, I’m switching between straight text and bullet points.
  • Add diagrams. Sometimes a picture really is worth a thousand words when it comes to teaching a concept. Consider process diagrams.

Don’t confront users with a wall of text. Make it as short as possible and break it up to make it easier to read.

Style choices

Be aware that some style decisions can cause issues for readers and viewers. Consider:

  • Contrast: People with colour blindness struggle to differentiate between colours or certain shades of colours. The key point is contrast: ensure that if your documentation is viewed in greyscale, it’s still perfectly usable. There’s a great article by Ivan Tuchkov: Color blindness: how to design an accessible user interface.
  • Text size: There are degrees of vision impairment. A lot of people can read just fine – IF the text is large enough. While most modern websites allow text size adjustments, a surprising number don’t, or do it badly. Your average PDF (non-reflowable) makes a terrible, horrible reading experience for someone who needs larger text. Ditto websites that aren’t responsive.
  • Text background: Some people can distinguish colours with no problem, but struggle to read text on a white background on-screen (too much light) or on a black background on-screen (too little light). Where possible, make sure the background on your end product can be customised by a user.

Use a high contrast between colours, and ensure that your documentation is reflowable and responsive.

Text-to-speech compatibility

Text-to-speech software reads out text from websites and documents. It can’t read text from images, and generally won’t differentiate between text styles. There are a few things that you can do to maximise a user’s text-to-speech experience:

  • Use alt-text in meaningful images or diagrams. The alt-text should explain the image well enough that the person listening can visualise it.
  • Don’t include large chunks of text in images. Type that text out.
  • Try it yourself. There are a number of text-to-speech options listed in this article: Text to Speech as a Support for Personalizing the Reading Experience.

Accessible documentation can be usefully read out loud by an app or browser add-on.

Learning styles

People consume and learn best in different mediums. Some will prefer text; others diagrams; others video; still others audio. While learning styles often aren’t considered under the umbrella of accessibility, considering them can help you to make your documentation easier for everyone to consume and learn from.

Take me for an example. I love to read. Words are awesome, as far as I’m concerned. But if you want to teach me a concept, draw me a diagram or two. And I’ve recently discovered that I retain information better if I listen to an audiobook over the printed or electronic book.

You can cater to people’s differing learning styles by diversifying your documentation offerings:

  • Provide information in different formats. For example, write a how-to article and produce a tutorial video. Important information should be available in multiple media.
  • Supply transcripts for videos.
  • Add diagrams to your knowledge base articles.
  • Make sure your written documentation is compatible with text-to-speech.

Consider the various learning styles when creating documentation.

Want to learn more about creating accessible documentation? Microsoft has a decent article: Make your Word documents accessible to people with disabilities. For websites, use the WAVE Web Accessibility Evaluation Tool.


Leave a Reply

Your email address will not be published.