Project:
A Technical Style Guide
for Internal Documentation
Accessibility
Much of the guidance in this Style Guide also applies to writing and creating accessible documentation. Making content accessible will help all readers enjoy it, whether they have a disability or not.
Accessibility involves a wide range of disabilities, including visual, auditory, physical, speech, cognitive, language, learning, and neurological disabilities.
The Web Content Accessibility Guidelines (WCAG) 2.0 https://www.w3.org/TR/WCAG20/
Be Concise. Always Consider the Reader.
Most guidelines include thinking of the reader and writing as concisely as possible.
Here are some of the points we already addressed in other parts of this guide:
- Use headings and subheadings to break up the text in a hierarchical way to make the text easier for readers and screenreaders to navigate.
- Use lists to organize related items.
- Use descriptive link text instead of generic text like “click here” to help screenreaders understand the link’s content.
- Use clear and straightforward language whenever possible.
- Emojis are better used sparingly because they’re difficult for those with visual processing issues to read when used one after another or in a list.
The other tips included are mostly formatting and structural things to keep in mind to ensure your documents are easy to navigate and understand.
- Avoid using color as the only means of conveying important information. Some people may be colorblind or may have difficulty distinguishing certain colors, so it’s important to provide additional cues such as text or symbols.
- Provide a transcript or summary of any audio or video content in the document. This can help people who are deaf or hard of hearing or who prefer to read rather than watch or listen.
Other Things that can Make it Hard to Read Online Content
- Small font size.
- Low contrast.
- Too many images or graphics: While images and graphics can be helpful in technical writing, having too many in a single document can make it difficult for people with vision impairments to navigate and understand the content.
- Overuse of capitalization or bolding.
- Poorly formatted lists.
Accessibility Testing
- Use accessibility testing tools, such as the WAVE tool, to check documents for accessibility issues
- Test documents with assistive technologies, such as screen readers, to ensure that they are accessible to users with disabilities
Accessibility Resources
- The W3C’s Web Accessibility Initiative (WAI) offers a range of resources, including an introduction to WCAG and a series of tutorials on specific topics: https://www.w3.org/WAI/
- The International Association of Accessibility Professionals (IAAP) offers a series of online courses on web accessibility, including a course on WCAG: https://iaap-hq.org/education/online-courses/
- The WebAIM organization offers a number of resources for learning about web accessibility, including a WCAG 2.0 checklist: https://webaim.org/standards/wcag/checklist