A11y-Friendly Documentation at Write the Docs Prague

A talk focused on assistive technology and how to build accessible documentation. This post contains the video and a full transcript of the talk.

Presented on September 10, 2018 at Write the Docs Prague.

🖥️ Slides
🔗 Resources

Thank you, so yeah, I'm Carolyn. I'm a frontend developer based in Berlin at a company called Blacklane. But before that, I was a technical writer so documentation holds a very special place in my heart. And I'm a little sick so apologies if I'm kind of sniffily or a little bit difficult to understand.

But ok, before we get going, I know what some of you are thinking - what the heck is a double one y, a eleven y or whatever's on the screen. This is pronounced 'ally' and you might be familiar with it if you've ever heard of i18n because they're both alphanumeric acronyms. That means that the letters between the first and the last have been replaced by a number representing the number of missing letters.

Now that acronyms are out of the way, let's talk about what accessibility actually is. Laura Kalbag outlines it well in her book Accessibility for Everyone. She defines accessibility in the physical world as the degree to which an environment is usable by as many people as possible and web accessibility as the degree to which a website is usable. We can think of both forms of accessibility as a form of inclusion. And this concept of inclusion has been finding its stride in the web development community and it's not that difficult to figure out why.

According to the World Health Organization, there are over 1 billion people globally who need an assistive device. With statistics like these, organizations and open-source projects alike have been realizing that they could be unintentionally locking people out of their products.

Accessibility can play a huge role in how we enhance people's experiences online. But in order to have products that are actually useful, we need to start understanding that people access the web and our documentation very differently. Assistive technology is one of those ways.

One of the most talked-about forms of assistive technology is the screen reader. This software takes in the information on the screen and turns it out in a Siri-like voice output, audio signals or even Braille.

This is a docs project that I'm working on with a Berlin-based developer named Sara Vieira. And there aren't that many components on this page - there's a search bar, a heading, text, some links. So let's see how a screen reader would consume this page. And let's pray that this works...

[start screen reader]
h t t p s colon slash slash
so - you - want - to - learn - graphql
dot s h slash
search edit text
heading level one waving hand hello
heading level two so you want to learn graph QL
learning new tech we know so we are here to help
first question did you know what graphql is
visited link yes
visited link no
voiceover off
[end screen reader]

So besides being great for catching typos, if you might have noticed that, screen readers have now made this web page accessible for those with visual impairments.

Another common form of assistive technology is keyboard navigation so this is when a person only uses a keyboard to access a computer or a website. Screen readers are often but not always paired with keyboard navigation. Shopify's developer portal is a great example because it is fully keyboard accessible and our focus as a user follows the visual flow of the page.

While this talk today will mostly focus on screen readers and keyboard navigation, accessibility on the web isn't limited to just that. People have diverse needs and so we've created a variety of technology to meet those needs.

There's navigation hardware, which is generally similar to a hand-operated mouse. Or switch inputs. With switch input software, it moves on the screen through the options and then people can trigger the switch when their desired option is reached. Or trackers, which rely on cameras to analyze the movement of a user's eyes or head to navigate or take action on the screen.

All of these technologies can help a wider range of humans, you know, access our websites and our documentation - but they can only help people to a certain extent. We need to think about how we program our sites so that we can optimize for other's success.

And fortunately, there's a strong business case for accessibility. Studies show that accessible websites have better SEO and usability, they encourage positive coding practices and they help us comply with any legal standards or regulations that we might need to follow.

But the thing is, while people have realized the benefits of this for their products - documentation is left out of the conversation. It just ends at the product and that's a big problem. Because if documentation is meant to serve as a tool for learning, discovery, comprehension then it must be included in those conversations.

One excuse I hear frequently when I talk to people about this is 'well, documentation is for developers.' That statement is problematic for many reasons - but let's start with this statistic: One out of every 200 software developers is blind or hard of sight. This will probably be the only time you see me quote a Stack Overflow survey. But if we think about how narrow the participation was for that survey, we can really imagine that there are probably so many other people out there that weren't accounted for. People who are probably trying to read our documentation.

Take freeCodeCamp contributor Florian Beijers. He was born blind, but he's able to code using a standard-issue laptop. He wrote a blog post where he explained that inaccessible docs and tutorials were one of his biggest pain points while learning. He writes, "The tutorials were undoubtedly good, but were completely unreadable for me." And then he goes on to explain some of the details that these documentarians might have missed.

I understand that accessibility can be, you know, seem really daunting and intimidating and kind of difficult to digest. But the reality is that most of us are already doing some form of accessibility. Choosing our language intentionally. Crafting user flows and learning journeys to fit a variety of needs. Providing content in most multiple languages. And testing our content between Chrome or Firefox or Safari, mobile, what-have-you. These are all forms of accessibility online.

We need to make our products and the supporting documentation accessible to all users - including users with needs that differ from our own. And to put it bluntly, this is our responsibility as documentarians - even if we're not the ones writing the code.

Anne Gibson, an independent accessibility consultant, puts this very well. She says, "We may or may not be responsible for writing the HTML, but if the developers we're working with don't produce semantic structure, then they're not actually representing the structures that we're building in our designs."

So whether you're an engineer, an information architect, a technical writer or something in between - we have we all have a hand in making our docs accessible.

So how do we actually accomplish this?

Let's start with structure and hierarchy. There's a good chance that you've heard that well-structured content is the best foundation for great documentation. Well, the same can be said for accessibility. A good question to ask could be: Would someone be able to quickly scan this document and understand the material?

Using subheadings to differentiate sections or breaking down text into short logical chunks help sighted users, sure, but it can also help those using a screen reader. But then we need to ask another question: Is the mark-up clean and structured?

Laura Kalbag, who I mentioned earlier, describes well-structured HTML as the secret weapon of accessibility. And that's because when we write well-structured HTML without altering the default behaviors, our pages becomes naturally accessible.

Take these examples so we can use an h1 (or heading 1) tag to describe to the user what's the most important thing on this page or what this page is about. We can use a nav tag to clearly indicate the start and end of our navigation bars or menus. An aside tag can indicate that this content is secondary to the main material - maybe a sidebar with some additional links. Or indicating whether we want a bulleted list (ul) or a numbered list (ol).

Fun fact: Screen readers will actually typically read the numbers or say the word bullet at the beginning of each list item even if those have been removed or hidden by CSS.

One way that we can also examine the page structure without diving into the code is by looking at the unstyled view. So this is the React Getting Started guide and this is roughly the way - this unstyled view - when you read it top to bottom is roughly the way it would be read by a screen reader.

We can also supplement our HTML with ARIA. ARIA, which stands for accessible rich internet applications, is a web standard that is particularly useful in conjunction with a screen reader. And to understand why ARIA is important, we need to think about things like custom components. So, you know, the things like drag and drop to upload content or those progress bars when you're watching videos or listening to audio. Those are great as a user, but they're really far from that document-based behavior that browsers and markup languages were originally designed for. They need a little extra help so that's where ARIA comes in.

There are three main features of ARIA that are defined in the spec. There's roles, properties and states - and we'll go through each of them briefly.

ARIA roles define what an element is or does and the roles are used as a layer on top of the existing markup. And for elements that don't have those implicit roles and the ARIA is actually prioritized over the HTML tag. So, for example, if you have a div with the role of a status then that screen reader will read it out as a status rather than a div.

Next is properties and ARIA properties define, you know, the properties of the element which gives them extra meaning or semantics. aria-labelled-by, for instance, allows you to put an ID on an element and then reference it as being the label for anything else on the page including multiple elements - which isn't possible with the label for input.

Finally, we have ARIA states and they are special properties that define the current condition of the elements. So aria-hidden is a nice example of this. If an element is only visible after a user takes some sort of action - like maybe an error message - then we would want to set the aria-hidden attribute while it's hidden to true. And then once the element is actually presented we would set the aria-hidden to false so that when someone's using a screen reader they'll know whether that element is actually applicable to them. States are different than properties because properties don't change throughout the lifecycle of an app versus states can change and are generally programmed by JavaScript.

But there's a time and place for ARIA. So, for example, you wouldn't put the role attribute like role='navigation' on a nav tag because it's already implicitly semantic. It should be placed on div, span or other more vague elements.

Focus indicators. So have you ever noticed those blue outlines that sometimes show up on links, inputs, buttons? These outlines are called focus indicators and browsers by default use the CSS pseudo-class to show these outlines on elements when they're selected. You might not think they're very beautiful, but focus indicators let people who are using keyboard navigation know where they are on the screen and help them understand where they are when they're navigating through your site. The elements that should be focused on are links, form fields, widgets, buttons and menu items. You can design focus indicators so that they fit the style of your site and that they go well with your brand. It's best to create something with like high visible contrast so that it stands out from the rest of the content.

When you're testing your site and if you try to use it only with a keyboard, you can ask yourself questions like: Can I tab through this entire page without getting lost? Do all of these focusable elements have that focused state? Can you operate tabs, accordions, menus, anything that you would as a sighted user or someone not using keyboard navigation as you should expect? And do you have a skip navigation link?

For those of you wondering what a skip navigation link is, I got you. So skip links are internal page links that are mainly used by screen readers for bypassing or skipping over redundant or repetitive content on a web page. They're usually not visible on the webpage because sighted users are able to just scroll past or ignore that content.

To show why skip links are necessary and important, let's take Twilio as an example. The Twilio docks are amazing and, you know, they're generally very accessible and a great resource to use. But you'll notice that if we look at the unstyled HTML - when we take away the link style sheets - there are a lot of menu elements and it takes time to get to the main content via screen reader. So adding skip links can help with this. Mozilla Developer Network (MDN) web docs are a very nice example. They have three different skip links. There's skip to main content, to select language, and skip to search.

Alright, next is images. Images can pose a problem because while screen readers are very sophisticated, they're not smart enough yet to interpret graphics. So we need to provide alternative text to help them out. There are two ways that we can do this. We can add an alt attribute within the img element itself or we can create that alternative text within the context of its surroundings. There are so many resources out there on how to do this well so I won't dive into that today, but I will show you an interesting nuance that I ran into while I was researching.

So this is another website by Sara Vieira called Is There Uber In? and it checks whether there's uber in a particular city. You'll notice that the Search by Algolia at the bottom is actually an image and it doesn't have any alt text so let's see how the screen reader would pick it up...

[start screen reader]
visited link image slash
918e15484df8b5806e
f5612f985260e9 dot SVG
voiceover off
[end screen reader]

If you missed it, that's what its readout: the image name. And this is because, as an attempt to provide useful information, a screen reader will oftentimes (if there's no alt text) read the name of the image itself or the source. So we want to make sure that, even if we do provide alt text, to make sure that our images have some sort of meaningful name as a fallback at least.

Alright charts and infographics. They're invaluable this documentation because they can take data and present it in this very clear and understandable format. But we need to provide text alternatives to explain this visual content. That's typically the most straightforward way to make this accessible. But we don't want to just dump all of the information from the infographic into the alt text or, you know, spit out all of the data from a graph. Because that kind of defeats the purpose of having the infographic in the first place.

So when we're crafting alt text for charts and infographics, we can ask ourselves: What are the highlights and the lowlights of this infographic? What are the most important or notable bits? I've also heard people say that it can help if you imagine trying to explain it to someone through the phone. You wouldn't read all of the data left-to-right, you would really find the most important parts.

Another question we should ask is: If someone can't see colors, is the message still clear? Elements with more complex information, like charts and graphs, it can be especially hard to read if you only use color to convey information. So we want to use other visual aspects to communicate information - like maybe shapes or labels or the size.

You can also try incorporating patterns into your designs to make the differences more apparent. It's not an infographic, but Trello's colorblind mode can provide really nice inspiration for adding text or patterns to your charts. If you want to check the contrast of something quickly, I use Color Oracle. It allows you to greyscale your screen instantly almost and there are also options for viewing your screen from the perspective of various different types of colorblindness.

Code snippets. So code snippets are very, and understandably, common in documentation. It's totally possible to make them accessible to people with visual impairments. We just need to understand what they expect to hear. This is an example of an if block in JavaScript according to a sighted user. But this is how it would be read out by a screen reader.

[start screen reader]
if left paren x equals equals true
right paren left brace console dot log
left paren quote hello world exclaim
quote right paren right brace
[end screen reader]

Some users turn off notifications for parentheses and the brackets. Others will substitute "left brace" for "lace" for example. While it may be verbose, it is accessible. Some tips that we can do while we are creating accessible code snippets is we can follow our semantic HTML principles and use a code tag. I would recommend trying to avoid using screenshots or images of code. Or at least making sure that there is a text alternative for it.

We can also use meaningful variable names. We don't want to use variable names that don't have any context like "foo", "bar", "baz". And I learned the hard way that you need to watch out for trailing spaces because the screen reader will literally read like "space space space space space space space". We don't want that unless it's necessary.

We've now started optimizing our components - but how can we actually test how accessible our site is? Or even see what we're missing? The great thing is that most assistive technology is free or inexpensive. This is great because it allows us to go directly to the source and experience the web in a similar way that our users might.

In terms of screen readers, there are some solid options like you might have heard I'm using Apple VoiceOver because I have a Mac and it's also available on iOS. You can turn it on quickly using Command + f5 and there's an introductory guide to get you going. If you're on Windows, there's NVDA which is open source and free. Whether you're using VoiceOver or NVDA, it's important to recognize that the way we, sighted users who might be new to this, might be very different than the screen reader experience of a non-sighted person, an expert who uses screen readers to consume the web daily.

If learning a screen reader is too time-consuming at the moment and you want to dive right in, most modern browsers and their developer tools have an accessibility tab. These show hints on the elements and how they'll be announced by assistive technology.

There are also many free extensions or validators out there to help us automate this accessibility testing without paying for a whole audit. We can scan for errors on our own sites. Axe is what I use and it's an open source rules library for accessibility testing. It was designed to enable developers to automate this accessibility testing on their own. It lives in the developer tools and when you analyze a site, this is the view. It comes up with issues, the number of occurrences, the element location, as well as suggested fixes for the problem.

Next one is WAVE. It's a browser extension and it is an accessibility evaluation tool that was developed by WebAIM. It provides visual feedback for the accessibility of your web content by injecting icons and indicators into your page. This is an example from Slack and you can see that we can see our semantic structure, we can make sure that alt tags are on all of our images and it can even give us warnings when, for example, links are maybe hard to read out of context and wouldn't make sense to a screen reader.

The bottom line is is that accessibility should be a requirement, not a nice-to-have. But in order for this to happen, we need to think about how we can change the processes within our organizations and workflows.

We could create and implement an accessibility policy. Now an accessibility policy sounds intimidating, but it can be anything from like a formal document posted publicly to an internal set of standards for your team to follow. Either way, it should be a statement that outlines your organization's, or your own, intentions towards your products, or in this case our documentation's, accessibility.

Oracle is a nice example of this because they actually give warnings about what screen readers might get wrong in their docs. They say that the conventions for writing code requires closing braces that should appear on an empty line. However, some screen readers may not read out that line if it's only consisting of one brace.

These don't always have to be made public by any means. But it could be nice to show your organization's intent, as well as let people know what they can expect.

We can also update our development checklists.
Many of the points I've mentioned could be added to a check. That way you can check or catch accessibility issues before it hits production. If you don't know where to start, The A11y Project has a pretty thorough one that you can use, reference and adopt for your own projects.

You can also dedicate a whole day to maybe browsing only with your keyboard or spend an afternoon learning how to navigate with a screen reader. Turn your settings to grayscale for a whole week. Learning how to use assistive technology ourselves is important because that's how we can build empathy towards people who have different needs than us.

You could also host an accessibility hackathon in your organization or beyond if you're open source. There's a lot that you can accomplish in just a few hours.

And you can also join the #a11y channel on the Write the Docs Slack. Since I joined, it hasn't been so active but maybe we can make it a place where we can ask questions and hold discussions around accessibility.

So I've shared a lot with you this past half-hour and this is only scraping the surface of this issue and how we can integrate accessibility into our docs. But please feel free to shout at me on Twitter, my handle is @carolstran , and we can explore these topics a bit further together.

But that actually wasn't the note that I wanted to end on. Rather, there was one thing that really stood out to me while I was doing this research.

"This is for everyone" is listed as one of the design principles for the UK government. In it, they say: "Everything we build should be as inclusive, legible and readable as possible. If we have to sacrifice elegance, so be it. We're building for needs, not audiences. We're designing for the whole country, not just the ones who are used to using the web."

And I believe that if we leave this conference today and adopt a similar mindset, we can also create documentation that is truly for everyone.

Thank you 🙏