Beyond empathy: write accessible documentation

In this talk from DevRelCon London 2023, Google technical writer, Sofia Emelianova, provides actionable advice on making documentation more inclusive and accessible.

Sofia emphasizes the importance of using inclusive language, writing clear instructions, reducing reliance on visual cues, ensuring readable text, creating meaningful links, writing valuable alt text for images, and making content translatable. She encourages all writers to strive for accessibility in their content creation.

Watch the video

Watch the video on YouTube >

Key takeaways

• Wait for people to self-identify before making assumptions about who they are and what language to use.
• Write clear instructions with precise language to be more inclusive and help users complete tasks.
• Use short and complete sentences in documentation.
• Use precise and concrete terminology, with defined or easily findable definitions.
• Use exact measurements when appropriate, such as “three” instead of “a few”.
• Use nouns instead of pronouns for third person references, even if it means being repetitive.
• Replace pronouns with the actual button names to ensure clarity in instructions.
• Provide clear instructions for navigating complex interfaces.
• Avoid assuming that users already know how to do things.
• Include necessary details for user success in instructions.
• Consider the visual abilities of readers and avoid relying solely on visual cues.
• Use text or alt text along with visual elements to convey important information.
• Choose colorblind-friendly palettes when using color as an indicator.
• Make instructions translatable to avoid mistranslations.
• Test your content, including alt text, to ensure accessibility.

Transcript

Kevin Lewis:

I have the great pleasure of introducing Sofia to talk about writing accessible documentation. Rather than take the stage, I’m going to hand it over. Thank you.

Sofia Emelianova:

Thank you.

Kevin Lewis:

And a big standing ovation.

Sofia Emelianova:

Welcome to “Beyond Empathy:, write accessible documentation” talk. My goal today is to give you actionable advice to make your documentation more accessible, and by speaking about beyond going beyond empathy, what I mean is when people talk about empathy, they define it and then not provide enough actionable advice, which I’m together with my co-author who is not present today unfortunately, and which I will attempt to fix with this talk. But before I start sharing advice, who am I? My name is Sofia and I’m a technical writer for Google. I develop documentation for Chrome developer tools and I enjoy teaching web developers how to debug the web. I am also an accessibility advocate, and I work with other authors and writers to encourage all writers to create accessible content. I’m here because accessibility is critical for current and future generations of developers and accessibility needs are more than the products that we build. We should create accessible content as well.

We may be moving beyond empathy during today’s talk, but that doesn’t mean that we shouldn’t have it and we shouldn’t define it first, like other speakers always do. A quick reminder that 4 billion people on earth are using the internet, 28% of them or over a billion internet users have some form of visual impairment. That can mean anything from wearing glasses to being colorblind, to having an astigmatism or even being entirely blind. 19% or 78 million internet users have a cognitive disability, for example, some intellectual disability or developmental disability. There are also folks with auditory speech and neurological disabilities, and I’m sure that there are people in this conference who have a disability visible or invisible as well.

And let’s start with the best practice, which is defining acronyms. You may have seen a11y or LI in this talk and elsewhere on the web, this acronym stands for accessibility as there are 11 letters between a and y. And the last reminder. Everyone in this room, everyone who watches this talk is a writer, and as writers, we should always strive to improve our content. Onto the first tip. It’s important to start by talking about inclusive language. Inclusive language avoids biases, slangs, or expressions that discriminate against groups of people based on race, gender, social, economic status, and everything else. Basically, it also avoids language that is ableist or discriminatory against disabled people. Inclusive language allows you to resonate with more audiences by speaking and writing in more impartial ways. No matter what we’re writing on or what we’re doing, we should always aim to be inclusive. When considering how to write and speak with inclusive language. In inclusive language, there are words that we should use and words we should avoid. Words to avoid may sound awkward at best and at worst they may be offensive. While a lot could be and has been said about inclusive language, let’s focus specifically on language for and about folks with disabilities. In general, it’s best to emphasize ability over limitations, avoid euphemisms and expect preferences for people’s identification and language to vary.

Often in technical language, we come across enable and disable as it relates to toggles, check boxes or other service activations, but we can use different more appropriate language such as turn on and turn off or start or stop. For example, in Google Chrome security settings, users can find an option related to enhanced protection, which allows for proactive protection against potentially dangerous websites. Previously, this toggle may have been referred to as enable or disable, but in this instruction, I’ve told the reader to go to settings and turn on the enhanced protections. When it comes to the word disabled, it’s not a bad word. People may have a permanent disability, be it physical or cognitive, and everyone in the world will at some point in time experience a temporary or situational disability such as a broken arm or an auditory impairment due to loud environment. That said, never assume how someone wants to identify.

Wait for people to self-identify before you make assumptions about who they are and what language to use. Tip number two, write clear instructions along with choosing precise language. To be more inclusive, it’s important to pick the best possible words to create the clearest instructions because this is crucial for helping our users complete their tasks. When you write documentation, clear instructions mean write short and complete sentences. Use precise and concrete terminology that is either defined or has easy to find. Definitions. Use exact measurements when appropriate, such as say three instead of a few. And for third person references, use nouns instead of pronouns, even if it means being repetitive. Here’s an example that could be improved by clarifying the pronoun. So there are two buttons. Which 1:00 AM I supposed to should move? Focus to it in the sentence may be confusing. You may have been able to guess that from context, but maybe not.

So by replacing it with the button name, the reader can be sure to know what the author means. This is especially important when it comes to explaining how to navigate. Complex interfaces in documentation tends to be clearer rather than briefer, but that’s not always necessary. Sometimes you have to trust your readers to understand from context, especially when space is short. For example, in UI texts. Let’s take a closer look at some technical examples. Many of us have created tests to make sure that our software works correctly. Instructions are also testable. There are many ways you can share about how to perform a task, and the detail you give depends on what your audience knows and on their experience that they have with your product. Often we assume people already know how to do things that are obvious to us. That’s called the curse of knowledge. You must be careful to remember that not everyone knows what you do. Here’s an instruction about how to test the user Agent reduction, which is an effort to minimize information shared in a user agent string introduced by Privacy Sandbox Initiative at Google. So the steps read that you should open their tools, then create a device, then configure it with a string and then emulate. But a lot of key details I’m missing the smallest to, which is what browser do you use? Most browsers have developer tools, but this feature is only available in Chrome.

Let’s look at a more detailed instruction. This version doesn’t make assumptions that you know how to find developer tools or know what the icons in the dev tools panel represent. These instructions, shared details that are necessary for user success. This can be further improved. We could clarify. Step three, provide examples for each field that’s represented in dev tools. Tip number three, reduce visual cues. It’s possible that people who read your content may be visually impaired, so you’ve got to ensure that your readers can understand important information regardless of their visual abilities. To get more specific, don’t rely exclusively on the visual elements to convey information, which are colors, patterns, images, phone styling, and directional words. Always use text or alt text along with visual elements. Here’s an example. Imagine that you’re looking for a recipe for Greek salad. You find a recipe online with this list of ingredients and the recipe says that red ones red ingredients are optional. Look at the list. Do you see a problem with it?

Well, relying on the color alone to indicate optional ingredients is a big problem. If someone is red, green colorblind, they won’t be able to tell the difference, and there’s no other indicator which can tell the reader what’s optional. Here’s an improved list of ingredients. This list explains where the optional ingredients both in text and visually, which means the list will still be clear if you remove the visual indicator. And I want to emphasize that using color is okay. Do use the color. However, I encourage you to always choose a color blind friendly palette of colors, but what’s most important is that there’s a second non-visual cue. By the way, you can emulate vision deficiencies, specifically several types of colorblindness using the rendering tab in dev tools. This way you can check how colorblind people see your website.

Tip number four, make your texts readable. Now, what could I possibly mean by that? Isn’t aren’t text always readable? As it turns out, not. So here’s an interesting piece of data for you. Another one about 84% of the top million homepages are on the web, had low contrast issues according to 2022. Report by web accessibility in mind, I think I failed to explain the acronym. So practically low contrast issues are the number one accessibility issue on the web, and it affects everyone, especially people with vision deficiencies. So Chrome deto can help you fix them with a few clicks. Actually, the color picker in the elements panel automatically calculates the contrast ratio and checks if it complies with web content accessibility guidelines or not.

Dev tools can also find all of the contrast issues on your website and them in one place. The CSS overview panel. More than that, you can also save all the changes that you make in dev toes directly to your local source files if you enable the workspace feature in the sources panel. And I will share a link to a detailed tutorial on the last slide. Tip number five, create better links. There are a number of aspects to consider in creating links from the target style to the actual linked copy. We’ve all seen click here, used in documentation, blog posts, and basically everywhere on the web using click here is like yelling at your reader that did you know we have a link? You should click it. For those who don’t use a screen reader to navigate, click here doesn’t give them any indication where they will be going when they click the link. When you use click here, you force the reader to search for context clues. It may sound actionable, but actually causes friction and increases cognitive load. For those who use a screen reader to navigate, click here links create huge obstacles. So you should provide consistent, unique, and meaningful copy in link text to help users know what will happen when they click so they can confidently take action.

Tip number six, a write valuable alt text. Alt text, which stands for, as you know, alternative text that lives within image HTML code and its intent is to describe images to those who can’t see them. Users may not see the image when the image isn’t properly rendering in the ui, which would mean they would see alt text instead. Other people use assistive technology like screen readers, and they heavily rely on alt text. By including alt text with your images, you ensure that the readers can appreciate the content on your website. Text in and around images should consider accessibility because that text presents key information about the image.

Here are some general best practices for alt text. Be contextual of the description, main characters, emotion or event, but be concise. For example, don’t start your alt text with the image of or screenshot of. Start immediately with the description. Write your all text and your image names in plain language. Read the copy aloud to yourself in the context and make sure it flows with the screen reader and use keywords sparingly. Keep in mind that not all images require alt text. If the image exists for decorative purposes and doesn’t carry important information, then there’s no need to add alt text image. Alt text shouldn’t repeat text from the body paragraph as well. Here’s an example from documentation. If I had included alt text, the screen reader would have read click toggle, device toolbar, toggles device toolbar to emulate your device. So kind reminder, make sure to test your content.

You may consider learning how to use a screen reader yourself. It can be quite handy actually not having to look at the screen all the time. Last tip for today. Tip number seven, make it translatable. Why is it important for accessibility? Well, imagine the following scenario. You use a screen to navigate the web. You are reading, for example, an instruction about the network panel in dev tools and English isn’t your native language, so maybe you’re using automatic translation in the Chrome browser for websites. And here’s an innocent looking sentence that I encountered. In real world, if you translate it to any other language, doesn’t matter what language. And then back to English, again, its meaning gets twisted. The context is about sending network requests and reloading web pages, and it’s not about executing prompts and rebooting the computer. So automatic translation mistranslate a lot. However, you can also use it to catch potential mistranslations even if you don’t know any other languages. Here’s a fixed example, rewritten to eliminate ambiguity in translation. The only change here is that log was transformed into register, which is arguably, which arguably doesn’t change the meaning.

This almost concludes my talk. So what’s the one thing that you’ll do differently? What will you start doing now? In every document you create, you can think about it and then let me know after the talk. Special thanks to my co-author Alexandra White, who couldn’t be here today, unfortunately. And here are the links. The first one is for more accessibility tips and more detailed accessibility tips, and the second one leads to the tutorial on how you can fix low contrast issues. The number one accessibility issue on the web with dev tools with several clicks. That’s it. That’s all. Thank you.