Matt Watson's Content Portfolio

Hello, and welcome to my page! I'm a content author and technical writer living in Raleigh, NC. I've put this site together to showcase some of my work. Please reach out if you have any questions or business inquires.

Accessibility in Documentation

Whenever I set out to start the task of writing I try and envision my audience. Who are they? What are their goals? How familiar are they with the subject matter? Keeping these things in mind helps me to stay on topic and tailor my message to their needs.

Of equal importance is how does my audience plan to consume my message. Are they using a mobile device? Might they find some images or text difficult to read? Are there words or phrases my audience might not be familiar with?

Good content is only good if your audience can consume it. So whether you’re writing for a small group, or like this piece any writer who might be interested, why not make sure that everyone can absorb what you’ve taken precious time to create.

  1. Purpose
  2. Accessibility Categories
    1. Text Chunking / Paragraph and Sentence Length
    2. Wording and Voice
    3. Visual Elements
    4. Inclusivity
  3. Resources

Purpose

This article collects accessibility considerations that I employ when crafting documentation. While it might not be exhaustive—accessibility being a wide and ever-evolving field—I feel it does an adequate job of collecting the items that I think of first.

Accessibility Categories

Below I’ve collected my thoughts into high-level categories. For easy navigation, please use the table of contents at the top of the page.

Text Chunking / Paragraph and Sentence Length

Breaking-up your text makes it easier to read. This, in turn, eases the cognitive load required to consume your document. It also helps to support readers of various reading levels and proficiencies.

Here are some rules I try to stick to when breaking-up my writing:

  • Sentence Length: 15 to 20 words tends to be the sweet spot.
  • Paragraph Length: Three to five sentences usually feels right.

Wording and Voice

Which words we use are just as important as how we use them. As such, it’s imperative that we avoid words our audience might be unfamiliar with, and avoid writing in ways that can be unclear.

  • Avoid jargon wherever possible.
    • You can often go with your gut here. Are you confused about a word? Then your reader will likely be confused too!
    • Still unsure if something’s jargon? Ask! Peer reviews are a great opportunity to have someone else let you know if something seems confusing.
  • Be weary of Latin abbreviations.
    • While e.g., i.e., and et al. can be quick shortcuts to bridge ideas, many people can be confused by them or get them mixed up. It’s often better to avoid them.
  • Always spell out acronyms the first time you use them.
    • This is a good practice even for terms we might believe to be widely understood, like FBI.
    • This helps us avoid assumptions about our readers and ensures that everyone consuming your content is on the same page.
  • Use the active voice whenever possible.
    • This helps ensure clarity in your writing.

Visual Elements

Using things other than just words can be a great way to elevate your content. They can break up your text to make it more interesting, and depict things that can be difficult to explain. Let’s just remember that using things in addition to words brings some additional accessibility considerations.

  • Don’t convey information with just color alone.
    • This could be problematic for those that see colors differently. Your “red” might not be my “red.”
    • This can be compensated for by using textures and patterns in addition to colors. Additionally, you can reference words in addition to colors.
      • For example. “Select the Exit button.” instead of “Select the red button.”
  • Use clearly-legible fonts…
  • …and high contrast colors.
    • While cream-colored text on a white background might make for an elegant wedding invitation, it’s not the clearest choice for a how-to article.
  • Add captions and alt text where possible.
    • Captions help to add contextual information to images.
    • Alternative or “alt” text provides a written description for visual elements. This is especially helpful for those utilizing a screen reader to review your content.
  • Be weary of using GIFs.
    • I…don’t love using GIFs. You can’t pause them, screen readers can struggle with them, and oftentimes they don’t appear correctly if you’re on a mobile device or if your internet is bad/inconsistent. That said, lots of people love gifs. So while I don’t think I can get away with saying “NEVER USE THEM!” I feel strongly is advising people to think twice before doing so.

Inclusivity

Your audience should not only be able to read your content, but they should also feel comfortable while doing so. As language evolves—which lets be honest, it’s doing constantly—we too must evolve with it. Below are some inclusivity considerations I keep in mind while writing:

  • Avoid unnecessary gendered language.
    • It’s often not necessary to distinguish between genders in writing. It’s also more inclusive to just generally use gender-neutral pronouns such as “they” or “their.”
  • Avoid outdated or offensive language.
    • Historically, the tech industry has used terms that are no longer accurate or inclusive. We should strive to avoid these. Some examples include: master/slave drive, tribal knowledge, blacklist.
    • Also, we should in general avoid offensive terms in our language regardless of the origin. (This hopefully goes without saying.)
  • Avoid ableist language.
    • This includes things like: blind, crazy, crippled, or dummy.

Resources

Below is a list of recourse I’ve found helpful and that have helped me write this article.

Posted in

Leave a comment