Suzanne AitchisonLast Hacktoberfest I contributed to the GatsbyJS 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!
I raised an issue in my own repo for my site Up Your A11y, 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 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:
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:
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 so I can keep making content 🙂
