Technical Writing for Web Accessibility: Guidelines and Resources
Technical Writing for Web Accessibility: Guidelines and Resources
How to write accessible documentation, with resources for learning more
Good documentation is accessible documentation. Technical writers routinely produce content for broad and diverse audiences and need to ensure their writing is clear, global, and unbiased. This article contains the rules and resources I rely on as a technical writer and content developer to ensure my writing is accessible and aligns with Web Content Accessibility Guidelines (WCAG), the international standard for web accessibility.
Read this article to get an overview of how to write accessible web content and to equip yourself with the best resources to dive deeper and learn more about writing for accessibility.
Contents
Introduction: What is accessibility and why is it important in technical writing?
Accessibility means making your product easy to use, for all users
“Accessibility” is different from “usability”
Why is accessibility important to the user experience?
What are the Web Content Accessibility Guidelines (WCAG)?
How to create accessible documentation and other online content
1. Use simple and clear language
3. Write accessible HTML and other markup
Introduction: What is accessibility and why is it important in technical writing?
Accessibility means making your product easy to use, for all users
Accessibility means providing comfortable usability to users, more so to disabled users. An accessible design enables any user of your target audience to use your product with ease despite any disabilities.
The American Psychological Association (APA) defines access as: “the elimination of discrimination and other barriers that contribute to inequitable opportunities to join and be a part of a work group, organization, or community.”
Good technical writing prioritizes access by eliminating barriers that might make it difficult for some users to use your product (or documentation) comfortably.
“Accessibility” is different from “usability”
Usability is the ability of the intended audience to use the product effectively, efficiently, and satisfactorily under the conditions in which it is meant to be used. It doesn’t necessarily consider diversity in the intended audience.
On the other hand, accessibility caters specifically to people with disabilities or special conditions that can make it difficult to live a normative life. Sometimes, usability practices don’t account for disability and cause more harm than good. Usability and accessibility should be considered in tandem to create an empathetic and inclusive design that’s helpful to disabled and abled users.
Why is accessibility important to the user experience?
-
When you write accessibly, you ensure every user in your target audience, regardless of their abilities and disabilities, can access your information easily
-
Being respectful of your target audience by writing with inclusivity and empathy improves overall customer satisfaction and signals a high-quality product
-
Attention to web accessibility removes bias and presumptions, improving the usability of the content for all the users
What are the Web Content Accessibility Guidelines (WCAG)?
The Web Content Accessibility Guidelines (WCAG), developed by the Worldwide Web Consortium (WC3), are the international standard for web accessibility. The most recent WCAG version at the time I’m writing this in April 2025 is WCAG 2.2.
The WCAG 2.2 contains 13 guidelines, organized under 4 principles: perceivable, operable, understandable, and robust. For each guideline, there are testable success criteria. The success criteria are at three levels: A, AA, and AAA.
The success criteria are what determine ‘conformance’ to WCAG. So in order to meet WCAG, the content needs to meet the success criteria. Details are in the Conformance section of WCAG.
For a short summary of the WCAG 2 guidelines, see WCAG 2 at a Glance.
Technical writers should rely on the WCAG 2.2 as the best reference for specific rules on writing accessible online documentation and complying with international web accessibility standards.
However, the WCAG is not the only useful resource on accessible web writing. Many organizations have published resources that are useful and relevant to creating accessible technical documentation, including:
How to create accessible documentation and other online content
To create accessible documentation, consider these four imporant guidelines: use simple language, reduce bias in writing, write accessible markup, and test your content.
1. Use simple and clear language
Accessible content is simple and clear. It avoids jargon, idioms, overly complex sentences. It also tries to avoid characters that can’t be read clearly by a screen reader.
Get familiar with the Federal Plain Language Guidelines for comprehensive guidelines on making writing easier for audiences to read and understand.
Here are a few key practices to ensure your writing is clear and concise:
- Write simple and concise sentences
- Write with plain language and shorter words. Instead of writing utilize, write use
- Avoid dashes. Instead of writing 1-3, write 1 to 3
- Avoid abbreviations. Instead of writing Feb, write February
- Avoid slang and colloquial language like clichés and idioms
- Avoid vague subject pronouns and unclear antecedents
2. Reduce bias in writing
Digital content, including documentation, needs to be written with attention to inclusion and diversity.
Reference the following resources for in-depth information about reducing bias in your writing and creating inclusive documentation:
- Reducing bias in your writing from Read the Docs
- Bias-free communication from Microsoft Style Guide
- American Psychological Association (APA)’s Guide on Bias-Free Language
- Google’s Developer Style Guide on Inclusive Documentation
Below are a few key guidelines to reduce bias in your writing.
Use gender-neutral language
Use gender-neutral alternatives for commonly gendered terms (for example, chair or moderator instead of chairman).
Don't use he, him, his, she, her, or hers in generic references. Instead, use person or individual, or rewrite the sentence. (Unless you’re writing about a real person — in that case, use the pronouns that person prefers).
Don’t use profane or derogatory terms
Avoid terms that have a history of being used in a divisive or derogatory way. Don’t use profane terms.
Aim for diversity in text, images, and made-up scenarios
In text and images, represent diverse perspectives and circumstances. Depict a variety of people from all walks of life participating fully in activities. Be inclusive of gender identity, race, culture, ability, age, sexual orientation, and socioeconomic class.
In made-up scenarios, avoid stereotypes in job roles and choose names that reflect a variety of gender identities and cultural backgrounds.
Write for a global audience
Show people in a wide variety of professions, educational settings, locales, and economic settings. Avoid using examples that reflect primarily a Western or affluent lifestyle. In drawings or blueprints of buildings, show ramps for wheelchair accessibility.
Be inclusive of job roles, family structure, and leisure activities. If you show various family groupings, consider showing nontraditional and extended families.
Be mindful when you refer to various parts of the world. If you name cities, countries, or regions in examples, make sure they're not politically disputed. In examples that refer to several regions, use equivalent references—for example, don't mix countries with states or continents.
Don't make generalizations about people, countries, regions, and cultures, not even positive or neutral generalizations.
3. Write accessible HTML and other markup
Technical writers do more than just write content — they’re often responsible for developing documentation sites and writing in HTML or other markup languages.
In these cases, the tech writer needs to consider web accessibility from the perspective of a front-end web developer.
Read HTML Accessibility from W3Schools for in-depth information on writing accessible markup.
Below are six key practices for writing accessible HTML or other markup.
Write semantic HTML
Semantic HTML means using correct HTML elements for their correct purpose. Semantic elements are elements with a specific use or meaning. For example, if you need a button, use the <button> element and not a <div> element.
Why is this important? Because semantic HTML gives context to screen readers, which read the contents of a page out loud.
Also, a button is accessible for people relying on keyboard-only navigation; it can be clicked with a mouse or keyboard, or tabbed between with a keyboard.
Use headings to show structure
Use headings to show a page or document’s structure, and the relationships between different sections. Don’t use headings for other purposes, like to make text big or bold.
Why is this important? Because Search engines use the headings to index the structure and content of your web pages, and screen readers use this structure for navigation.
The different types of heading specify the outline of the page. Use <h1> headings for main headings, followed by <h2> headings, then <h3>, and so on.
Alternative Text
Make sure to include alternative text for images. The alt attribute provides alternate text for an image if the user can’t view the image for some reason. If a browser can’t find an image, it displays the value of the alt attribute. Screen readers read the alt text.
The value of the alt attribute should describe the image. For example, “A nighttime view of Taipei’s skyline.”
Declare the Language
Make sure to declare the language (for example, English) of the web page by including the lang attribute inside the <html> tag. Language information helps search engines return language-specific results, and is also used by screen readers that switch language profiles to provide the correct accent and pronunciation.
Create Good Link Text
Write link text that explains clearly what information the reader will get or what website they’ll be redirected to by clicking on the link. For example, “Read more about HTML accessibility.”
Be mindful of color and contrast
Content should never rely solely on color to convey meaning. Also, there must be sufficient contrast between text and background because some people cannot read faint text. Adhering to these guidelines benefits users with visual impairments and color blindness.
4. Test your content
To ensure accessible HTML and good keyboard accessibility, consider testing your content.
Interactive elements such as forms, buttons, and navigation menus must be usable via keyboard alone. Collaborate with developers or download screenreader software to test accessibility and identify content or instructions that depend on mouse interaction.
Resources and style guides
Resources from W3’s WCAG:
- WCAG 2.2 Standard - the complete W3 Web Content Accessibility Guidelines (WCAG) 2.2
- WCAG Documents - WCAG 2 supporting documents and supplemental guidance. Helps you know where to go for which type of information
- WCAG 2 at a glance
- How to Meet WCAG (Quick Reference) - a customizable quick reference to Web Content Accessibility Guidelines (WCAG) 2 requirements (success criteria) and techniques.
Style guides from Microsoft, Google, and APA:
- Microsoft Writing Style Guide - accessibility guidelines in Microsoft’s Writing Style Guide
- Google developer documentation style guide - accessibility guidelines in Google’s developer documentation style guide
- APA Style - accessibility guidelines in the APA style guide
Miscellaneous resources:
- Atlassian Design System - Inclusive Writing
- Google’s Developer Style Guide on Inclusive Documentation
- Microsoft Style Guide on Bias-Free Communication
- American Psychological Association (APA)’s Guide on Bias-Free Language
- Writing inclusive documentation, from WordPress
- A11Y Style Guide
- The Accessibility Cheatsheet | bitsofcode
- Accessibility terms - Microsoft Style Guide
- WCAG Compliance - | Level Access
- The Must-Have WCAG Checklist | Level Access
- HTML Accessibility from W3 schools
I'm a technical writer and UX writer for commercial SaaS products.