Refactoring condescending language with alexjs
Tags: a11y, webdev, showdev
Published: 2020-04-25 14:22:03

Last Hacktoberfest I contributed to the [GatsbyJS](http://gatsbyjs.org/) documentation, where they were encouraging refactors for tone, content and accessibility. Some of the tweaks they wanted to make were to replace any use of words like "easy" and "simply" - I hadn't thought about it before but it seemed like a great idea!

How frustrating is it when you're bashing your head against a problem, only for the docs to tell you how **easy** this is!

![Frustrated developer throwing computer](https://media.giphy.com/media/L4AQvif7x9fS8/giphy.gif)

I raised an issue in my own repo for my site [Up Your A11y](https://www.upyoura11y.com), and when I *finally* got around to doing something about it, it felt a little overwhelming looking at all these static MDX files I have. Luckily, there's a package for that!

## Enter, Alex

[Alex](https://www.npmjs.com/package/alex) is an NPM package that acts like a linter for insensitive writing in your project. In their own words:

> Whether your own or someone else’s writing, alex helps you find gender favoring, polarizing, race related, religion inconsiderate, or other unequal phrasing in text

### Getting started

You can install alex globally with the command `npm install alex --global`. Once you have it installed, you can run the linter from your terminal with the `alex` command. 

My main content files are stored in separate folders, and running `alex` alone only executes in the current directory. Happily, I was able to pass a pattern to alex instructing it where to look: `alex content/topics/**/*.mdx`

The initial run picked up 104 warnings(!!) Here's a snapshot of what the output looked like:

![Terminal output showing warnings including usage of words like 'easily' and 'just'](https://dev-to-uploads.s3.amazonaws.com/i/8eg9eces2xq1ff3rl2ts.png)

### Common themes

My 104 warnings had a tonne of commonality. They can be broadly grouped as:

- Usage of "easy"/"easily", "simple"/"simply" and "just" in my tutorials
- False positives for use of words like "color" and "special" (in my context not relating to people)
- A few sundry warnings on use of "men" and "women" (related to statistics I've quoted) and "disabled"/"disability"

## What I changed

In the end, I made changes to 12 articles, with 60 additions/deletions. You can see the full pull request here:

{% github https://github.com/aitchiss/up_your_a11y/pull/61 %}

The vast majority of what I changed was some really unfortunate instances of "easily", "simply", and so on. I still have 39 warnings when I run alex in my project, but I'm happy for now that I've considered those and don't believe they need changed due to their context (as described above).

## What I learned

My main take-away is that I am inevitably going to write things like "this simple tweak", "this can be easily solved by..." and so on in my content. Honestly, when I'm in the flow of writing I feel like these are nice, softening, approachable words to use. Almost as if I'm reassuring the reader: "Yes, you can do this! Don't worry".

I'm way more aware now that even if those words are having the desired effect for some people, there is a whole other group who I am potentially alienating, frustrating and accidentally making them feel the opposite of what I intended.

I'm probably unlikely to be able to change my default way of writing overnight (I wish!), so in the meantime I'm going to commit to running alex each time I add a new article to my site.

I'd be really interested in hearing from anyone else who's used this tool, or something similar, and how you got on!

--------
*Did you find this post useful? Please consider [buying me a coffee](https://www.buymeacoffee.com/mgkZuRU) so I can keep making content* 🙂