Do you practice Inclusive Design? Do you check the accessibility of your digital products? How accessible is your project documentation? Not sure where to start? Don’t worry, I’ll give you some ideas you can use to help make your projects more inclusive. This will help your current and future team.
A few things better documentation can do for your team:
- Reduced barriers for outside contributors
- Faster on-boarding for new employees
- Lower time-to-repair for outages
- Improved customer relations
- Higher job satisfaction
- Fewer code defects
We often assume our documentation readers have the same levels of experience, education, and familiarity with code concepts. This tends to create barriers for people we never intended to exclude. Clear and simple writing helps everyone understand more information faster.
Every Project, Every Team
Lone developers of private software and members of distributed OSS (Open Source Software) teams alike will eventually struggle with poorly documented code. Most developers have felt that cringe of reading old code like a horror story. As it unfolds, they already know terrible things will happen while remaining powerless to stop it. Maybe you did this only to realize it was your code all along–plot twist!
As we age, we forget things, our thought patterns change, and our bodies fail. Our institutions change, our teams change, and society evolves. Technology expands, guidelines emerge, and collective wisdom grows. Inclusive documentation remains our best defense against constant change. Become the author of documentation that others want to keep reading or help write.
Here Today – Wrong Tomorrow
Inclusive documentation can multiply the positive impact of a project. But it’s work. Often more work than the code it represents.
Many teams struggle to keep documentation up-to-date. So, they often avoid writing it. Even after the team realizes the importance of good documentation, they fail to maintain its accuracy. A few practices and techniques can help make this chore simpler and less time-consuming.
Teams should enforce documentation during code review. Documentation can take the form of a single markdown file in a module’s folder or as embedded code comments. It’s common practice to put *.test.js files in a web module’s folder but less common to see *.readme.md. I tend to do this for large or complex modules. I use VSCode for my JavaScript projects because it turns JSDoc-formatted code comments into syntax and grammar hints. That prevents mistakes. Tools like documentation.js can then generate API (Application Programming Interface) documentation from the same code comments.
If your project puts examples in the documentation, you should test them. When I don’t directly build examples from tests, I like using jsmd for my README.md files. It uses a code comment convention to generate assertions and test my sample code automatically.
Accessibility
Complete, correct documentation creates a foundation. Now you can use some testing tools to ensure accessibility. Tools like axe help find template or formatting problems in the markup. WCAG (Web Content Accessibility Guidelines) addresses the accessibility of content in section 3.1, Readable but you need different tools to check content-related issues.
“Because no one has ever complained that something was too easy to read.”
Individuals can write documentation in a popular editor to make it more readable:
- Hemingway Editor – web app
- ProWritingAid – Chrome extension
- Grammarly – Chrome extension
Pay special attention to Reading Level, another WCAG criteria, while using these tools. Try to reach a score of at least 60 (grade 9) on the Flesch-Kincaid Readability test, considered the lower end of the “Plain English” range.
Most of our accessibility testing tools look at how the system presents content. We need tools that inspect content. You may have heard of linters: a class of tools that analyze source code “to flag programming errors, bugs, stylistic errors, and suspicious constructs.” Most programming languages have them. ESLint, a popular linter, uses an AST (Abstract Syntax Tree) to analyze JavaScript. Likewise, remark uses an AST to analyze markdown. We can think of remark as a linter for writing documentation. It can check your spelling, word choice, and sentence structure. Another tool, Vale, encourages organizations to build on this model and create their own style guides.
I know what you’re thinking. “I need this now and for always.” If it’s only for you, consider making a pre-commit hook. To add these tests to your project’s CI (Continuous Integration) process, look at Write the Docs. If your team uses Github, you can use Probot or test-drive their promising new beta service, Github Actions to create reusable “apps.”
Approachability
Simple writing helps everyone. But consider the new team member, the first-time contributor, a new developer, or non-developer. Plain language may not be enough to make your documentation less intimidating. WCAG mentions three other areas that can help:
I realized that keeping my linter’s dictionary file close to “default” helps me find what words and terms I need to define. Sometimes you can’t avoid using technical terms but you should do your best to introduce them in an approachable way.
When someone feels “outside” of the community or team, two specific documents can help ease their fears. Teams should add CONTRIBUTING.md and CODE_OF_CONDUCT.md files in each project. You can find examples in your favorite projects or from community efforts like contributor covenant. Make sure you apply your writing style guide and automated checks against these files. I’ve seen some well-intentioned policies with inaccessible writing. These documents should not sound like lawyers wrote them.
These documents help everyone understand the processes you need to follow. Readers learn what to expect when they contribute and how the team handles conflict. Adding these documents reduces emotional barriers that make projects more approachable.
Huggability
Huggable projects don’t have rough edges or pokey parts that could hurt someone trying to get close to them. I don’t always know what huggable is but I can learn what isn’t huggable.
Many of the tools I reference have default settings based on years of research and lived experience. These defaults can help you avoid common pitfalls. One of my favorite tools, Alex, catches insensitive and inconsiderate writing. While there’s no WCAG success criteria for respect, insensitive language is a pokey part you can remove from your projects. Alex, built entirely on remark, also inspired a VSCode plugin, Slack App, Github Bot, and more.
When someone raises an issue with your project they’re often trying to hug your project, not find fault or hurt your feelings. Don’t get defensive. Instead, try to focus on which pokey part you can remove or what rough edge you can smooth over with better documentation. Remember that creating the issue included work and thought. Work, in any form, is a contribution. Treat people in your issues the same way you treat other contributors. Together, you can make a huggable project.
