Technical writing is a vital skill for more than just internal documentation -- we need it to provide instructive text that helps users interact with our apps and tutorials for projects in our own fields of interest that we want to share with others who might find it helpful or interesting, to name a couple of examples. Like any other form of writing, we want to make sure that what we produce is widely accessible and not harmful to our audience, but even with the best of intentions we sometimes experience pitfalls with our use of language.
WCAG 2.1 SC 1.3.3: Sensory Characteristics (Level A) has some helpful guidelines for us to get started:
"Instructions provided for understanding and operating content do not rely solely on sensory characteristics of components such as shape, color, size, visual location, orientation, or sound."
For example, “Click the green button” does not meet this criterion – the only option for the learner to determine which page element they should interact with is visually identifying it by color.
This can be remedied by including more information about the element – if the green button has a label, “Click the green ‘Save’ button” would comply with general accessible language guidelines, because an alternate method of identifying the correct button is now provided; eliminating the sensory language altogether, e.g. “Click the ‘Save’ button” would also work.
In the case of infographics or charts that may use sensory characteristics to highlight specific information, “The brachial plexus is highlighted in blue” with no additional description does not allow visually impaired users to determine or understand the location of the object in question. “The brachial plexus, highlighted in blue, is a network of nerves in the shoulder that carries movement and sensory signals from the spinal cord to the arms and hands” is acceptable for both sighted and visually impaired users, because it gives an alternate method for locating the object in question that is not reliant on visual identification.
Instructions required to complete a suggested activity to enhance learning or understanding should also consider this guideline. If an activity cannot be designed in such a way that it avoids the use of highly visual or audio materials, alternate methods for conveying the same information or successfully performing the task for visually impaired or D/deaf and hard of hearing learners should be included. This same consideration can be applied to teaching the use of specific tools, such as we might include in a crafting tutorial – could a learner with a sensory, cognitive, or motor disability a.) use the same tool as a non-disabled learner, and b.) use it in the same way? If the answer is “no,” and an accessible tool for that purpose exists, it should also be acknowledged and any differences in usability explained to an equivalent level.
Some words and phrases used in common parlance may be unintentionally frustrating and/or hurtful to learners. Avoid language like “simply do the action” or “just complete the task,” because it implies that the subject being discussed “should” be easy for the learner; however, what is a simple task or concept for one person may be more difficult for another. Other words and phrases that assume cognition include (but are not limited to) “as you can see,” “easily,” “merely,” and “obviously.”
Sensory language in calls to action or instructions should also be carefully evaluated. In the context of cross-referencing information or a link to obtain additional information, “see” is widely acceptable; more debatable is the use (especially when frequent) of “look at” and “watch,” although as of this writing, this is still a consideration under discussion in the accessibility community rather than being a concrete guideline. When more neutral language can be used while preserving meaning – e.g. “play the video” instead of “watch the video” – consider doing so.
This is by no means an exhaustive list of potential accessibility issues we could fall into with our technical writing, but hopefully can serve as a launching pad for conscientiously improving our word choices. In the case of writing copy for our websites and apps, tools like Alex.js in addition to human review may be helpful in avoiding racist, sexist, or ableist metaphors that are common in Western culture among English-speaking individuals. The Augsburg University English writing lab also provides for public use a PDF of potential microaggressions and ableist language, along with suggestions on how to replace them with non-harmful phrasing to preserve intended meaning.
Because our understanding of how language can affect members of our communities is so dynamic, social standards for our own word choices are always evolving. It is inevitable that we will sometimes make mistakes, but as long as we treat these instances as learning opportunities and commit to updating our own knowledge accordingly, we can continue to build safe, welcoming spaces for all.