Inclusive Documentation With alex
Tags: documentation, webdev, opensource
Published: 2019-02-19 14:14:43

---
title: Inclusive Documentation With alex
published: true
tags: Documentation, webdev, opensource
canonical_url: https://www.kennethlarsen.org/inclusive-documentation-with-alex/
---

 ![Inclusive Documentation With alex](https://www.kennethlarsen.org/content/images/2019/02/Sk-rmbillede-2019-02-19-kl.-15.00.54.png)

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](https://alexjs.com/) 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](https://github.com/get-alex/atom-linter-alex)
- Sublime: [SublimeLinter-contrib-alex](https://github.com/sindresorhus/SublimeLinter-contrib-alex) (by [@sindresorhus](https://github.com/sindresorhus))
- Visual Studio Code: [vscode-alex](https://github.com/shinnn/vscode-alex) (by [@shinnn](https://github.com/shinnn))
- Gulp: [gulp-alex](https://github.com/dustinspecker/gulp-alex) (by [@dustinspecker](https://github.com/dustinspecker))
- Slack: [alex-slack](https://github.com/keoghpe/alex-slack) (by [@keoghpe](https://github.com/keoghpe))
- Probot: [linter-alex](https://github.com/swinton/linter-alex) (by [@swinton](https://github.com/swinton))
- Vim: [ALE](https://github.com/w0rp/ale) (by [@w0rp](https://github.com/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](https://github.com/yohanmishkin/ember-cli-alex) (by [@yohanmishkin](https://github.com/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](https://github.com/emberjs/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](https://github.com/emberjs/website) 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.