If you listen to audiobooks, you might be surprised to learn that the very first one was recorded almost a century ago, in 1932, by The American Foundation for the Blind.
Maybe you’re one of the 140 million Americans who use an electric toothbrush, which were first developed 70 years ago for people with limited motor skills. Have an Alexa or Google Home? You can also thank the disabled community: the first full text-to-speech synthesizer was invented in 1976 to assist people with vision issues.
What does this have to do with programming? I recently presented on creating at inclusive tech environment at the Helvetic Ruby conference in Zurich, Switzerland. You can watch my talk below, and read on for more tips.
Disability in tech
When we talk about accessibility in tech, we typically focus on external users and the front-end interface. However, this approach overlooks a key audience: the disabled workers who produce the tech itself.
It might surprise you that, statistically speaking, there are lots of folks in the tech industry who could benefit from accessibility improvements. Just to throw a few examples out there:
- 8 percent of men in the U.S. are colorblind
- 20 percent of people in the U.S. have dyslexia
- ~1 in 10 developers globally have a concentration and/or memory disorder
- ~1 in 50 developers globally are blind or have vision issues
And it’s not just about long-term disabilities: there are also a plethora of conditions or experiences that can make someone’s job more challenging, such as healing from a broken arm, caring for a newborn, struggling with mental health issues, or joining a team whose primary language isn’t the same as yours.
At Red Canary, one of our core values is to “be kind and authentic,” and we want ALL of our team members to feel supported and included. This requires us to be deliberate about creating a tech environment that actively empowers everyone.
Products and processes developed to increase accessibility benefit everyone; increasing accessibility truly is a win-win situation.
As history demonstrates, products and processes developed to increase accessibility benefit everyone; increasing accessibility truly is a win-win situation. And it doesn’t have to be a massive overhaul: small, individual-led efforts can make a big difference.
How-to: Accessible coding
As you review some of the below recommendations, you might find yourself thinking something along these lines: “Ok, I understand why this might be easier for some folks to read, but I just can’t stand how it looks.”
And I get that feeling! We all have ways we prefer to do things, especially with our code.
But let’s pause for a second. Imagine you’re working in an office and don’t get to choose your desk chair. Instead, it’s something your company provided. It’s made of hard plastic, has weird decorative spikes on the armrest, and doesn’t have wheels. (It’s also too short for you.) But your office manager just *loves* the aesthetic, and insists you use it.
Technically, you’d be able to perform your responsibilities while using that chair, but it would be a frustrating experience. And that’s the key: while preference is personal, accessibility is global. Our colleagues’ needs inherently outweigh our stylistic inclinations.
How do we try to meet those needs in our code?
Readability
Especially with a language like Ruby—which comprises much of Red Canary’s backend codebase, and was created to be akin to writing sentences in English—we aim to make our code human-friendly and readable.
Some of the ways we do this:
- Favor semantic method and variable names over metaprogramming or shorthand
- Avoid abbreviations and acronyms (e.g., use “external” instead of “ext.”)
- Use full words for placeholders in loops (instead of single letters)
- Craft method and variable names that are pronounceable, which helps not only for screen readers, but also for pairing
Line length
While the average person consumes text fastest at 100 characters per line, we prefer roughly 50 to 75 characters per line. Shorter line lengths also benefit people who use screen readers, people with dyslexia, and people with concentration or focus issues, just to name a few. Additionally, emphasizing shorter lines can help us simplify our code, such as forcing us to break up multi-nested ternary operators (true story).
As a real-world example, The New York Times website—which is designed to encourage reading large blocks of text—caps their line length at 74 characters.
Consistency
Establishing guidelines for code standards is a crucial piece of making your code more accessible. Linters are especially great for this; Red Canary uses multiple, covering our CSS, Haml, JavaScript, Ruby and Docker files. The idea is that the code structure and syntax are predictable and consistent, and anyone can look up the rules to ensure they’re meeting expectations.
Folks only have to learn one pattern, and they can trust everyone else to follow the same pattern.
Comments
This might be the most controversial topic covered in this post, but code comments are amazing and broadly underutilized. There’s an old truism that “good code doesn’t need comments,” but we say, why not both? Clean, readable code, AND helpful, contextual comments. The goal for our code is that it’s easily consumed by people of varying skills, experience, and familiarity, and comments are a useful tool.
Specifically, consider adding a comment when:
- The code is expected to change in the near future
- It concerns mission-critical functionality
- Changing the code could have unintended consequences
- The code is particularly complex or complicated
- It relates to an external service or vendor (for example, including a link to related vendor-hosted documentation)
Specs
The same guidelines above regarding code also apply to specs, but there are additional opportunities to improve the accessibility of your tests, specifically.
Be descriptive
High test coverage not only helps prevent bugs or missing requirements, but also serves as built-in documentation. With this in mind, it can be useful to think of tests as a form of storytelling:
- What is the code doing, and why?
- What is it NOT doing, and why?
- Who (or what) do we expect to interact with this code?
- What happens if there’s an error?
Verbose, descriptive tests benefit a variety of people, including those with focus or concentration issues, early career folks and people new to the codebase. (They can also be a lifeline for future-you, trying to remember what you were thinking when you wrote that code 8 months ago.)
“DAMP” is the new “DRY”
When it comes to specs, it can be easy to over-refactor, and create specs that call multiple different files or rely on reams of shared code. These kinds of tests are challenging to parse or debug, which has a ripple effect: it takes longer for new developers to understand the test suite, straining velocity and potentially leading to product liabilities.
For specs, we prefer a DAMP approach (“descriptive and meaningful phrases”) over a strict DRY approach (“don’t repeat yourself”). In practice, this means things like:
- Defining your test data in the file where it’s being tested
- Avoiding shared data and examples, where possible; where not, use comments to help guide folks through the specs
- Individual tests have explicit, descriptive assertions and variables, and they can be updated independently of each other
How-to: Accessible documentation
Treat it like code
The same accessibility / readability guidelines that apply to front-end code apply to whatever platform you use for your documentation, namely:
- Using hierarchical, semantic HTML
- Ensuring your color choices pass contrast standards
- Using subheaders to make the content skimmable
Use “simple” language
“Simple” language, or “plain” language, refers to a communication style that emphasizes comprehension over style. It assists a wide variety of people, including those:
- Whose primary language isn’t the same as the document’s language
- Who use a screen reader
- Who don’t have much experience with the document’s topic
- Who are using an automated translation tool
- Who are stressed or multitasking, and have finite ability to focus
Key ways to write “simply” include avoiding abbreviations or acronyms, assuming the reader has little context, and limiting sentences to 15-20 words. You can also test your writing for comprehension, using a tool such as Hemingway or Ginger Writer.
Images and video
All images should have a caption. The same is true for video documentation; video transcripts not only make the content available for folks who have hearing issues, but also enable people to interact with the content according to their individual learning styles.
Don’t rely on images of code samples or images of terminal output: instead, include the actual text. This is not only for the sake of screen readers, but also for viewing more easily on smaller devices, as well as for instances where someone wants to copy the code (there’s nothing more frustrating than trying to highlight text, only to discover it’s a JPG!).
If your platform doesn’t support great syntax highlighting, you can include the image AND the actual text.
General tips
Here are a few more tips for creating more accessible documentation:
- Write informative link text (e.g., “Vendor documentation” instead of “Click here”)
- Spell out dates to avoid ambiguity (e.g., May 10 instead of 5/10)
- Avoid using socially charged terms for technical concepts (e.g.: “core feature” instead of “native feature”)
Remember: Accessibility on the back end doesn’t require a major reworking
Instead, it primarily consists of individual, low-effort, consistent practices. At Red Canary, we’re working as a team to create a technical environment where everyone can reach their full potential. These best practices not only benefit people at our company with short-term and long-term disabilities: they benefit everyone, empowering people to contribute in ways that match their skills and abilities.