Inclusive Documentation With alex

There is a lot of helpful open-source tools out there that can help us improve our documentation. In general, automated tools can help us remove the overhead that exists in maintaining documentation and let us spend our valuable time on writing the content. Sadly, these tools aren't perfect, and you have to be aware of a few things. In this post, I'll show you how to refactor our current documentation using alex.

The development community doesn't have the best reputation when it comes to being inclusive and considerate. Even though a lot of great efforts has been made to improve this, we're still far away from the goal. There is however one thing we can do to help promote this - and it all starts with documentation.

alex is an automated tool that enables us to catch inconsiderate and offensive language within our documentation and even our code base.

Getting started

To get started we have to cd into a directory containing one or more markdown file and run npx alex. (or npm install -g alex; alex). Now the output in the terminal should tell you if there are any current issues with our documentation.

If we want to have this working as a linter inside our editor there are a few integrations available:

• Atom: atom-linter-alex
• Sublime: SublimeLinter-contrib-alex (by @sindresorhus)
• Visual Studio Code: vscode-alex (by @shinnn)
• Gulp: gulp-alex (by @dustinspecker)
• Slack: alex-slack (by @keoghpe)
• Probot: linter-alex (by @swinton)
• Vim: ALE (by @w0rp)

If we're using Ember.js there's even an Ember addon that will run alex within our test suite to also catch offensive namings within our code:

• Ember: ember-cli-alex (by @yohanmishkin)

Refactoring Our Documentation

So, we have alex running, and it's listing a lot of issues - how do we proceed from here?

There will be words that alex catches that might not be inconsiderate or offensive at all - and that's fine. It's a linter, not a human. This is where we as a company or maintainer get to define our rules. Let's say we have written the following sentence:

To try out the new React hooks visit the guides.

alex will return the following:

Be careful with hooks, it’s profane in some cases

Now, while it's true that hooks is profane in some cases, some cases it's not. If we would like to ignore this warning since it's not profane in this context we add an ignore statement above the sentence like this:

<!-- alex ignore hooks -->
<p>To try out the new React hooks visit the guides.</p>

If we run alex once again, it will return no errors or warnings.

But what if all we write about is React hooks? It's quite cumbersome to add the ignore statement every single time we mention React hooks. Thankfully, alex supports an ignore file.

In the repository for the Ember.js website we have an ignore file that looks like this:

{
  "allow": ["color", "dad-mom", "her-him", "he-she", "hook", "hooks", "harder"] 
}

As long as this file is named .alexrc and placed in the root of the project it will automatically ignore these words.

Whatever is left after ignoring non-offensive words are things we should fix. Say we have a README.md that contained the following section:

It writes all changes to the **master server** thus, the slaves were read-only copies of master. 

If any of you guys would like to contribute please do so 

alex will raise issues about this text. First of all, the use of master/slave is considered to be insensitive. Instead, we should use terms like primary/replica which - besides being more inclusive - is a much more precise term.

Another issue we have is the use of guys. alex tells us that "guys may be insensitive, use people, persons, folks instead". In this case, I agree that guys is insensitive and hinting that males are the ones being encouraged to contribute.

After a few changes we now have:

It writes all changes to the **primary server** thus, the replicas were read-only copies of primary. 

If any of you folks would like to contribute please do so 

Much better.

Keeping It Clean

Besides having the linter in our IDE and running alex on our local machine, there is something we could do to catch errors going forward.

If we again have a look at the Ember.js website repository we find a script that is being run by the CI.

git remote add base https://github.com/emberjs/website.git
git fetch base
BLOG_HAS_CHANGES=$(git diff --name-status base/master source/blog/2*)
if [[$BLOG_HAS_CHANGES]]
  then
    alex $(git diff --name-status base/master source/blog/2* | sed s/^..//)
fi

This script checks whether the blog has any changes - since the blog is currently the only place where alex is being run - and if so alex is being run in the diff only. This is especially important when we already have a lot of documentation. Changing everything in one go is often not a possibility, but catching it going forward is doable.

So, every time a pull request is raised alex will make sure that we consider our language.

It might be overwhelming at first, but I do think it is worth investing in improving our documentation to be more welcoming and inclusive.