Web accessibility for your documentation by Carolyn Stransky

At Write the Docs Prague 2018 we listened to a fantastic talk on accessibility in documentation by Carol Stransky.

Carol is a front-end developer at Blacklane and formerly a technical writer. This means Carol has a fantastic perspective on accessibility in docs, and her talk could be summarized as being about accessibility in design by default.

Carol says, “This is for everyone” is part of the design manifesto of the UK Government Digital Service. The GDS is a department of the UK government responsible for designing digital products on behalf of all other departments.

So in the spirit of this ethos, the technologies we create should be aimed at all users – not just a select few. Sadly, this is not always the case. While many software products are accessible already, documentation often gets left by the wayside.

At the moment, the prevailing paradigm is not working – accessibility is a “nice-to-have” rather than a prerequisite.

The A11y project

The A11y project was set up with the aim of tackling this problem of accessibility in design. A11y is pronounced “alley” and is a numeronym – in this case it’s short for “accessibility”.

A numeronym is a number-based word and A11y is popularly used across the web to discuss accessibility. It’s a hashtag on twitter, a category on The Practical Dev, and even a Write the Docs Slack channel.

The A11y website is a resource for web developers to help make their applications more accessible.

Image caption: Homepage of the A11y Project

The standards body for the web, the W3C, has a website for web accessibility standards called the Web Accessibility Initiative. Although the W3C has improved it in recent times, many designers have struggled with in the past.

As a result, the A11y project aims to make accessibility in design more accessible.

Image caption: Definition of web accessibility

What is web accessibility

Web accessibility is defined by A11y as:

“Accessibility is often viewed as making your site work on screen readers. In reality, web accessibility is a subset of UX focused on making your websites usable by the widest range of people possible, including those who have disabilities.”

Web accessibility is a well-known issue for web designers, and yet many people still find it difficult to use the internet for a number of reasons. Just as a building should be accessible to as many people as possible by having ramps and lifts, so should a website be accessible by being designed correctly.

“Accessibility should be a requirement, not a nice-to-have,” says Carol. But the reality is that most documentation is not that accessible to a wide audience, and part of the reason for this is a lack of understanding of what accessibility means.

Why we need accessibility

The hardware, operating system and software systems are the bridge between your documentation and the end user. These are aspects of a web interface that many people wouldn’t think twice about, and yet they are absolutely crucial for assistive technologies to work.

Many technical writers forget about this layer of the technology and focus only on writing their documentation well.

Technical writers should think about usability in a more integrated way, instead of focusing primarily on aesthetics. You should consider the overall interaction between the human and the technology, as well as the writing.

It’s about technology being designed by the few, for the many – and that technology is not designed in an accessible way by default.

And as comes up so often, documentation is all about empathy (or it should be). While accessibility is often factored into product development, according to Carol, documentation is another story.

Myths of accessibility

One of the posts on the A11y website deals with a common myth that accessibility only refers to blind people. This couldn’t be further from the truth, and they refer to the four categories of accessibility:

• Visual
• Auditory
• Motor
• Cognitive

The computer system itself is difficult to use for people who are blind or partially sighted. They have to use screen readers or other assistive technologies to access websites (which we’ll go into later).

People with cognitive impairments like Down’s Syndrome may struggle to use the web if pages are not structured clearly.

People with motor impairments use assistive technologies such as eye trackers or operate their computer with a single button, so they navigate websites in a different way.

People with auditory impairments won’t be able to understand media such as videos and recordings that rely on sound, so sound shouldn’t be a prerequisite of your design.

Assistive technologies

Now we’ll look at some assistive technologies that help people access the web.

Screen readers

A screen reader is a Text-to-Speech tool which turns information on the screen into audio, which the computer then transmits from speakers or headphones.

One of the downsides of screen readers is they cannot interpret graphics. That’s why we need to use the alt text tag for images, which means writing a short line of information explaining what an image represents.

Using images in tweets on twitter also presents a problem for screen readers. If the meaning of your tweet depends on an image, then a screen reader won’t be able to read that image in any sensible way – unless you use the alt text tag on Twitter when you post the image.

Another good thing to remember is that screen readers will read out hashtags as well as the rest of the tweet. If your hashtag has multiple words that run together and no capital letters, they won’t make any sense to screen readers.

One of the most interesting parts of Carol’s talk was when she showed us what using a screen reader is like. Use NVDA on Windows or VoiceOver on Mac to view your web page like a screen reader does. You can now check how accessible your documentation is.

Keyboard navigation

Most software interfaces assume you would use a mouse rather than keyboard navigation, but a keyboard is definitely a form of assistive technology for some people. Frequently you will find keyboard navigation and screen readers together.

Focus indicators help keyboard navigators know where they are on a screen, and you should be able to navigate through your site using just a keyboard. For example, all links, form fields, widgets, buttons, and menu items should be clickable.

Image caption: Example of a focus indicator from Stripe documentation

Skip links help you skim over redundant content, instead of having to click through every single element to get to the right place.

For example, there might be a line of text or a button you can click to take you past the header and menu straight to the page content. Like this:

Image caption: Example of a skip link on the A11y website

Navigation hardware

Image caption: Navigation hardware – touchscreens, mouth sticks and foot-operated mice

Touchscreens allow users to interact directly with the content of a screen using their finger or a stylus.

Mouth sticks are for people who have limited strength and dexterity to type and press buttons, as are foot-operated mice.

Switch inputs

Image caption: Switch inputs – mechanical buttons, foot plates and electronic sensors

People with physical or cognitive disabilities may also use switches such as mechanical buttons, electronic sensors and foot places to operate their computer.

Trackers for eye, head, and dwell control

Image caption: Trackers – eye, head, dwell control

Trackers that respond to eye or head movements are used by people with paralysis to control their computers.

Making the case for accessibility

You may think that the majority of people won’t have a problem with your documentation. You’re also under time and budget constraints, so you design your documentation as well as you can.

Although everyone has the tendency to operate from within the realm of their own biases, many people have differing needs when it comes to documentation. For example, one in every 200 developers is blind or hard of sight.

Image caption: One out of every 200 software developers is blind

Documentation is crucial for developers to do their jobs, so what about that one in every 200 developers who can’t access your documentation?

Carol says that accessibility concerns create a good foundation for future-proofing your content so there’s also a strong business case for accessibility. Having an accessible website improves your SEO ranking, and also means you’re compliant with legal standards.

We have the power to change our processes and workflows, such as making an accessibility policy. Technical writers are responsible for ensuring accessibility in their documentation at the technology level, even if coding is not directly in their job description.

It’s essential to think about how we program our sites and do it in an accessible way. Most assistive technologies are free or inexpensive so we can use them to gain empathy for users of these technologies.

Accessibility in action

Carol used the VoiceOver screen reader to read out an image name for the company logo on the Algolia search engine. It was just a long string of numbers, which obviously sounded horrible when read out by a screen reader.

As a result, the team at Algolia updated that part of their website to make it more accessible, which they also shared in the Write the Docs Slack channel.

Quickfire accessible design tips

It’s important to note that when your website is styled using CSS, this doesn’t change the underlying HTML – which is the part of an application that most Assistive Technologies will interact with. So for example, a numbered list hidden by CSS will still be read out (number by number) by screen readers.

• Well-structured HTML is naturally accessible – eg you should be using a single h1 tag and then h2 tags for subheadings.
• ARIA tags can be used for accessibility – stands for Accessible Rich Internet Applications and is a way of making modern web content and applications more suitable for Assistive Technologies.
• Images need to be named sensibly – screen readers will even read out long strings of numbers.
• Trello has a colorblind mode – there are apps online that also help you change your screen to grayscale to check how your design shows up for colorblind users.
• Code snippets should be accessible – use meaningful variable names and avoid “trailing spaces” which will be read out by screen readers.
• Wave is a handy tool for checking the accessibility of your web page – type in your URL to diagnose errors.
• Learn how to use assistive technologies – this will help you to build empathy for the people using them.

Final remarks

This talk was significant for the many companies who design and sell their own software products. Accessibility is very important and it was fantastic to have the issues highlighted in such a compelling way.

Here’s a link to Carol’s speaker deck, a link to her talk on YouTube, and a link to the A11y website. Join the #a11y channel on the Write the Docs Slack, and follow Carol on Twitter at @carolstran.

Our knowledge base software KnowledgeOwl enables technical writers to publish outstanding documentation. Sign up for a free trial. 

Photo credits: Attribution-NonCommercial-ShareAlike 2.0 Generic (CC BY-NC-SA 2.0)