Beyond Empathy: Write Accessible Documentation  ## Metadata - Author: [[Dev Rel]] - Full Title: Beyond Empathy: Write Accessible Documentation - Category: #articles - Document Note: --- tags: [#Accessibility, #Documentation, #InclusiveLanguage, #WebDevelopment, #A11y, #TechnicalWriting] - #Accessibility - #Documentation - #InclusiveLanguage Author: Sofia Emelianova Source: Beyond empathy: write accessible documentation (Talk at Google) Reference: [YouTube](https://www.youtube.com/watch?v=b5J4bc-7vZ8) date created: 2025-08-23 23:59 --- # Title: Beyond Empathy: Writing Accessible Documentation ## Table of Contents: - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📖 References](#-references) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🔍 DARVO Analysis](#-darvo-analysis) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) --- ## 📝 Summary: Sofia Emelianova, a technical writer at Google, argues that accessibility in documentation must go **beyond empathy** by providing **actionable practices**. She highlights seven tips: 1. Use **inclusive language**. 2. Write **clear instructions** that avoid ambiguity. 3. Reduce reliance on **visual-only cues**. 4. Improve **readability** and contrast. 5. Create **meaningful link text**. 6. Add **concise and contextual alt text**. 7. Make documentation **translatable** for global users. The talk emphasizes that **everyone is a writer**, and all writers carry responsibility for inclusivity and accessibility. --- ## 📖 Main Content: Accessibility is not optional—it’s central to usability and inclusivity. Documentation that is not accessible excludes large groups of people, particularly those with visual, auditory, or cognitive disabilities. Sofia stresses moving from empathy (feeling for users) to action (changing how we write and present information). - **Empathy as a starting point**: Understanding challenges is important but insufficient without systemic changes in writing practices. - **Statistics as proof**: Over a billion internet users experience visual impairments, and millions face cognitive challenges. These numbers highlight accessibility’s global importance. - **Practical guidelines**: Replace jargon and euphemisms, write clear instructions, avoid pronoun ambiguity, ensure readability, and test documentation with screen readers and translation tools. --- ### 🗒️ Notes - [00:04](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=4) Accessibility must go beyond empathy → actionable strategies. - [02:43](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=163) **Inclusive language** avoids bias, euphemisms, and inappropriate terms like "enable/disable." Prefer "turn on/off." - [05:15](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=315) Write clear instructions → short sentences, avoid pronouns, trust context when space-limited. - [07:40](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=460) Beware **curse of knowledge**; not all readers share your assumptions. - [10:08](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=608) Don’t rely on visuals alone; always provide alt text or text equivalents. - [12:46](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=766) Low contrast is the **#1 accessibility issue** on the web; Chrome Dev Tools offers fixes. - [15:30](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=930) Alt text must be concise, contextual, and avoid redundancy. - [17:53](https://www.youtube.com/watch?v=b5J4bc-7vZ8&t=1073) Automatic translation can distort meaning—use it to catch ambiguities. --- ## 📖 References: - [WebAIM: 2022 Accessibility Report](https://webaim.org/projects/million/) - [W3C: Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) - Chrome Dev Tools Accessibility features documentation --- ## 🗣️ Paraphrase: 1. Original: *“Inclusive language avoids biases, slangs or expressions that discriminate… It also avoids language discriminatory against disabled people.”* → Rephrased: Accessible documentation uses neutral, precise wording that does not demean or exclude individuals, particularly those with disabilities. 2. Original: *“Click here doesn’t give indication of where users are going… it causes friction and increases cognitive load.”* → Rephrased: Vague link text like “click here” forces readers to guess context, creating confusion and unnecessary cognitive effort. --- ## 📰 Newsletter: ✨ **Beyond Empathy: Building Accessible Docs** This week’s highlight comes from Google’s Sofia Emelianova, who reminds us that accessibility in documentation is about **action, not just empathy**. From using **inclusive language** (“turn on/off” vs. “enable/disable”) to writing **clear instructions**, ensuring **colorblind-friendly cues**, and providing **concise alt text**, Sofia’s talk delivers practical steps that make docs usable by everyone. For WordPress contributors, these practices translate directly into better **plugin guides, handbooks, and onboarding docs**—where accessibility gaps often block contributors. 📚 Watch the full talk here: [Beyond empathy - YouTube](https://www.youtube.com/watch?v=b5J4bc-7vZ8) --- ## ✅ Action Items: - Apply **inclusive language** standards in WordPress training docs. - Audit WP.org contributor documentation for **contrast issues and “click here” links**. - Advocate for alt-text inclusion in all plugin/theme guides. - Model accessibility practices in GoDaddy and WPCC doc contributions. - Position accessibility as a **core OSPO responsibility** for governance and community inclusivity. --- ## 🧪 Hypotheses: - H1: Accessible docs increase contributor retention in open-source projects. - H2: Replacing ambiguous link text reduces user errors. - H3: Alt text and translation-ready content expand global contributor participation. ### 📊 Methodology: - Run A/B tests comparing task completion rates with accessible vs. non-accessible docs. - Audit GitHub/WordPress issue trackers for accessibility-related complaints. - Survey global contributors about translation challenges. ### ❓ Questions: - How can WordPress integrate accessibility checks into its contributor handbook workflow? - Should WPCC establish accessibility doc standards as a baseline for project inclusion? ### 🔮 Future Research: - Effectiveness of automated accessibility linting tools in documentation. - Cultural differences in accessibility expectations for open-source documentation. ### 💡 Implications: Accessible docs aren’t just ethical—they expand contributor diversity, reduce onboarding friction, and strengthen open-source ecosystems long-term. --- ## 🧠 Learning Styles Assessment: - **Visual**: Strong (examples of colors, alt text, Dev Tools). Could use infographics. - **Aural**: Medium (talk format supports auditory learners). Add audio summaries. - **Verbal**: Strong—clear, descriptive language. - **Kinesthetic**: Limited—could add exercises (“test your docs with a screen reader”). - **Logical**: Strong—uses data (WebAIM report, stats). - **Social**: Medium—encourages discussion but no interactive prompts. - **Solitary**: Medium—encourages reflection at end. - **Naturalistic**: Minimal—could add analogies linked to nature. --- ## 📊 Accessibility Assessment: - **Screen Reader Compatibility**: Emphasized; best practices included. - **Keyboard Navigation**: Not addressed—should be. - **Contrast & Readability**: Strong—low contrast flagged as #1 issue. - **Text Resizing**: Implied, but not explicit. --- ## 🌍 DEIB Assessment: - **Cultural Relevance**: Limited—primarily Western context. - **Inclusive Language**: Strong—examples of ableist phrasing replaced. - **Neurodiversity Support**: Some clarity tips; could add more structure. - **Representation**: Focused on disability; - Summary: In this talk, Sofia Emelianova discusses the importance of writing accessible documentation. She emphasizes the need for inclusive language and provides tips on how to achieve it, such as avoiding biases and discriminatory language. Sofia also emphasizes the importance of clear instructions and provides guidance on how to write concise and precise instructions for users. She highlights the importance of reducing visual cues and ensuring that important information can be understood regardless of visual abilities. Sofia also discusses the importance of creating better links and providing meaningful alt text for images. Lastly, she emphasizes the importance of making documentation translatable to avoid potential mistranslations. - URL: https://www.youtube.com/watch?v=b5J4bc-7vZ8 I have the great pleasure of introducing sopia to talk about writing accessible documentation uh rather than take the stage I'm going to hand it over thank you thank you and a big standing evasion standing [Music] OAS welcome to beyond beyond empathy WR accessible documentation talk um my goal today is to give you actionable advice to make your documentation more accessible um and by by speaking about Beyond going Beyond empathy what I mean is um when people talk about empathy they Define it and then and then not provide um enough actionable advice which I'm together with my co co-author who is not present today unfortunately um which I will attempt to fix with this talk um but before before I start sharing advice uh who am I um my name is Sophia and I'm a technical writer for Google I develop documentation for Chrome developer tools um and I enjoy teaching web developers how to debug the web I am also an accessibility Advocate and I work with other authors um 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 um we may be moving beyond empathy during today's talk but that doesn't mean um that we shouldn't have it and we shouldn't Define it first like um like uh other speakers always do um a quick reminder that um 4 billion people on Earth are using the internet 28% of them or over a billion internet users have some form of visual uh impairment that can mean anything from wearing glasses to being color blind to having an stigmatism or even being entirely blind um 19% or 78 million internet users have a cognitive disability um 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 um and let's start with the best practice which is defining acronyms you may have seen um a 11 y 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 um everyone in this room everyone who watches this talk um is a writer and as writers we should always strive to improve our content um on to 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 um and everything else basically it also avoids language that is aess 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 turn off or start or stop for example in in Google Chrome security set settings users can find an option related to enhanced protection which allows for proactive protection against potentially dangerous websites previously this toggo may have been referred to as um 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 world 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 impair 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 in complete sentences use precise and concrete ter terminology that is either defined or has easy to find definitions use exact measurements when appropriate such as say three instead of a few um and for third person references use nouns instead of pronouns even if it means being repetitive here's an example um that could be improved by clarifying the pronoun um so there are two buttons which one am I supposed to should Mo move Focus to the it in the sentence may be confusing you may have been able to guess um 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 comp interfaces in documentation tend to be clearer rather than rather than briefer but that's not always necessary sometimes you have to trust your readers to understand from Context especially was 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 instruct are also testable there are many ways you can share um about how to perform a task and the detail you give depends on what audience of on what your audience knows um and uh on their experience that they have with your product often we assume people already know how to do things that are obvious to us and that's called The Curse of knowledge you must be careful to remember that not not everyone knows what you what you do um here's an instruction about how to test the user agent reduction which is an which is a an effort to minimize information shared in a user agent string introduced by uh um by privacy sandbox initiative at Google uh so the steps read uh that you should open Dev tools then create a device then configure it with a string and then emulate um but a lot of key details are missing the smallest of 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 def tools panel rep represent these instructions share 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 TOS um 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 um to get more specific don't rely exclusively on the visual elements to convey information which are colors patterns images font styling and directional words um 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 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 color blind 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 leave list of ingredients this list explains where are where the optional ingredients um both in text and Visually which means the list will still be clear if you remove the visual indicator um 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 pallette of colors um but what's what's most important is that there's a second nonvisual cue by the way you can emulate Vision deficiencies um specifically several types of color blindness um using the rendering uh tab in Dev tools this way you can check how your color how color blind people uh see your website tip number four make your texts readable now what could I possibly mean by that isn't it isn't aren't texts always readable um as it turns out not so um here's an interesting piece of data for you another one about 84% of the top million homepages uh on the web had low contrast issues according to 2022 report um by by web accessibility in mind I think another another I failed to uh explain the acronyms see here's so um practically um low contrast issues are the number one accessibil accessibility issue on the web and it affects everyone especially people with vision deficiencies um so Chrome Del tools can help you fix them um with a few clicks actually um the color Pi picker in the elements panel automatically calculates the contrast R ratio and checks if it complies with web content accessibility guidelines or not um Dev tools can also find all of the contrast issues on your website and list them in one place the CSS overview panel more than that you can also save all the changes that you make in Dev tools 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 um tip tip number five create better links there are a number of aspects to consider in creating links from the target style to the actual link linked copy um we all seen click here used in documentation blog posts and basically everywhere on the web um 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 they will be going when they when they click the link um 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 um 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 write um valuable alt text alt text which stands for as you know alternative text uh 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 assist assistive technology like screen readers um with 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 shoot should consider accessibility because the that text presents key information about the image um here are some general best practices for alt text um be contextual contextual of the description main characters emotion or event but be concise for example don't don't start your alt text with the image of or screenshot of start immediately with the description write your alt texts and your image names in plain language read the copy allowed to yourself in the context and make sure it 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 uh to add alt text image Alt text shouldn't repeat text from the body parag paragraph as well um here's an example from documentation if I had included alt text the screen reader would have read click toggle device toolbar toggle device Toolbar to emulate a device so kind reminder make sure to test your content um you may want to you may consider learning how to use a screen reader yourself um it can be quite handy actually not having to look at the screen all the time um last tip for today tip number seven make it translatable um why is it important for accessibility um well imagine the following scenario you use a screen reader to navigate the web you reading for example an instruction about the network panel in Dev tools um and English isn't your um native language so maybe you're using automatic translation in the Chrome browser for webites um and here's an innocent looking sentence that I encountered in Real World um 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 pag and it's not about executing prompts and rebooting the computer um so automatic translation mistranslates a lot however you can also use it to catch potential mistranslations even if you don't know any other languages um 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 um which arguably doesn't change the meaning um this almost concludes my talk um so what's the one thing that you'll do differently what will you start doing now um in every document you create um you can think about it and then let me know after the talk um special thanks to my co-author Alexander white who couldn't be here today unfortunately um and here are the links the first one is for more more accessibility T tips and more detailed accessibility tips and the second one is uh leads to the tutorial on how you can fix um low contrast issues the number one access accessibility issue on the web uh with Dev tools with several clicks that's it that's all thank you [Music], Beyond Empathy: Write Accessible Documentation, Dev Rel, 01hde9mkw65mm1cmnjpbmg2t03.