A guide to coding accessible developer tools

A guide to coding accessible developer tools

When we talk about accessibility in the tech industry, most conversations are centered around the end user. But how accessible are the tools we code for other developers?
Part of
Issue 3 October 2017

Development

When we talk about accessibility in the tech industry, most conversations are centered around the concept of the end user: people with varying levels of technical skill who interact with the software that we write for them. There is, however, another accessibility discussion that we should be having: How accessible are the tools we code for other developers, our colleagues, our open-source communities, our peers?

Just like there is no perfect average end user, there is no perfect average programmer. Every one of us is different when it comes to our abilities, experiences, and lives. But we tend to have the same goals—such as leveraging others’ code when we can, so as not to reinvent the wheel. Every developer wants to write the best tool they can for their peers. They want to make their tools easy to use, help save others’ time, and preserve their cognitive load. They often want those tools to reach as many other developers as possible—and accessibility is an important and integral part of that strategy.

There are many areas where developer tools can be made more accessible. Let’s discuss a few of them.

Documentation

Documentation (or ‘docs’ for short) is an important consideration when it comes to ensuring your developer peers can use your software in the way you intended, ideally without frustration. Documentation is an instruction manual. It replaces the need for a developer to read your source code in order to understand how to interact with your library or tool. Therefore, creating highly accessible docs can have a large impact on both the usability and popularity of a project.

All documentation should be clear, thorough, and accurate. Consider that your user community will likely differ in English comprehension skills and primary language spoken. Although most popular programming languages use English for syntax and keywords, programming has global skill adoption. It can be tempting to write docs heavily laden with tricky language, local slang, and colloquialisms, but this can cause barriers for others’ comprehension. Assess the readability and clarity of your docs before publishing them to ensure that an expansive audience can benefit from them.

One tool for assessing your documentation accessibility is the Hemingway App. The Hemingway App analyzes text and scores it based on tiered reading levels, starting at the U.S. fifth-grade level. The assessments can help you spot potentially difficult passages in your documentation. It also goes one better: It suggests substitutions and amendments as highlights throughout your piece. It’s available as a text editor applicationa web app, and even a linter, if command line applications are your thing.

Translating your docs into languages other than English is another way to increase the accessibility of your software for other developers. In many developer communities, there are translation working groups that volunteer their time to translate library documentation and programming language manuals. Online translation services, such as Rev, are also available, often for a fee. If your library or tool has some form of financial support, this can be a great investment to help broaden adoption and access. If you still need convincing, I highly recommend watching Mariko Kosaka’s eye-opening talk, “Re-inventing the Rosetta Stone Together.”

Visual content, such as architectural diagrams, is very useful for conveying concepts within documentation. Color blindness, blindness, and vestibular conditions should be taken into account when producing diagrams. For color blindness, consider the color use in a diagram. Is all of the information conveyed clearly without having to rely on color to communicate an idea? For blindness, provide text descriptions of a diagram. For vestibular conditions, avoid any animations that might trigger motion sickness, dizziness, or seizures.

If video is featured in your documentation, include closed captions as an option. Any audio should have an accompanying written transcript.

Lastly, documentation presented in HTML is very accessible to screen readers and assistive HIDs (human interface devices) when written with semantic HTML practices. Consider distributing your documentation as HTML.

Operating system support

Operating system choice is always a hot topic among developers, and it’s easy to assume that everyone uses the same operating system as you and your immediate peers. These assumptions can vary within developer communities, particularly by programming language. But keep in mind that other developers may choose an operating system for reasons that you, personally, wouldn’t necessarily expect. For example, some blind programmers prefer to work on Windows. Many developers also use Windows because PCs tend to be more affordable machines than those from other manufacturers. A developer may need specific assistive-tech–related software in order to effectively use their computer, which can lock them into Linux, OS X, or Windows, depending on their situation.

There are several relatively straightforward things you can do to help ensure that your software is accessible from an operating system perspective. The first is to know what tools are available on each platform.

For example, when writing install scripts, consider using an alternative to Makefiles. Makefiles do not work out of the box on Windows, which can cause a lot of confusion when a developer clones your repository and follows the installation steps in the documentation. Consider writing installation scripts in the programming language the library is written in, which will help smooth out at least some differences across operating systems.

Also, test your software on as many operating systems as you can. Ensure any native code builds correctly without any errors. Using continuous integration services (such as Travis CI and AppVeyor) with good-quality tests can set you up well to ensure your software works everywhere.

If it’s not possible to support every operating system, be explicit in your documentation about what is and isn’t supported. This saves developers a lot of potential headache up front, and might even spur a contribution to your project.

Package size and dependencies

There are still many locations around the world where internet connections are expensive, metered, and slow. Including dependencies that are superfluous can literally cost developers on bandwidth. This is a real problem that can prevent access to your library.

Excessive code bloat can also slow developers down significantly when downloading, building, and transpiling. Keeping the feedback loop small is key to productive development. Slower machines will have trouble crunching repetitive development builds if there’s a lot to process. Not everyone can afford the latest, fastest computer equipment. Test your tool from time to time on a slower computer than your own.

You can help mitigate both of these aforementioned problems by only shipping the code and assets that are absolutely necessary—this can make a big difference to the folks using your tool. Things to cut down on commonly include sample assets you are testing with locally or large raster files of the project’s logo, which wouldn’t necessarily be useful or needed when using the code itself.

There are multiple ways to solve this, the most common being ‘ignore’ files. Tools such as Git and npm allow you to ignore certain directories and files present in your working space when committing code. Many other software sharing and packaging ecosystems have a similar feature. Publishing smaller code footprints helps everyone.

Making tools accessible benefits everyone

We’ve covered several areas of developer tools where accessibility can be improved. Accessibility is one of the yardsticks for evaluating the quality of a tool. The more accessible you make it, the more the community who uses it can grow. Accessibility is not just an end user concern, it is a peer concern. It’s on us to further progress the software we use every day—we write it for each other, after all.

Further reading

About the author

Suz Hinton is a software developer who enjoys coding for the web platform, the internet of things, and creative endeavors. She’s also an accessibility advocate and open-source maintainer. Suz currently works as a Cloud Developer Advocate for open source and IoT at Microsoft.

@noopkat

Artwork by

Yukai Du

yukaidu.com

Buy the print edition

Visit the Increment Store to purchase print issues.

Store

Continue Reading

Explore Topics

All Issues