Leading up to (and during) the month of October, we want to help you discover open source projects to work on, and put your Hacktoberfest contributions to excellent use. Meet Carolyn Stransky, Software Developer based in Berlin.
Check out this page regularly for more interviews with contributors & maintainers
I'd like to talk to you about an initiative I started last year during Hacktoberfest, which aims to remove condescending language like "simple", "easy", "just", "clearly" from open source documentation. I ended up submitting over a dozen pull requests to different projects, like Jest, Cyprus, Storybook, that were all later merged.
I chose to do this because removing these words is an active way to make documentation more inclusive. We don't want our documentation to make assumption because a "simple" concept for one person, isn't always simple for another person. Plus, if you don't normally have the time or capacity to do open source, or you want to dive into a new codebase this month, I found this to be a high impact, but low effort way to get involved with almost any project.
I'd like to take you through the steps I took, and maybe you can replicate during this Hacktoberfest, cause really there is still so much more documentation that needs this kind of attention.
I broke it down into 4 steps:
- First you want to open an issue describing your mission,
- Second is to use a language linter to flag any condescending terms,
- Replace instances of condescending language,
- Open a pull request with your proposed changes.
If you aren't a regular contributor to a project, I really suggest opening an issue before starting any work. This gives you an opportunity to describe the value that a change like this would bring, and see if maintainers are open to that change. Spoiler alert: not all of them are. On the other hand this allows maintainers to suggest a preferred format for the changes. For instance: submitting 1 pull request for every section of their Docs, instead of all at once. Or maybe they have any existing linters that you can work with or modify.
Once you've gotten the ok from the maintainer(s), you can really start to dig into the Docs. You could manually search for every term within the documentation but this can get quite tedious - and you might miss terms and variations, like "easily" instead of easy". That's why I'd suggest using AlexJS - an open source language linter designed to catch polarizing writing in Markdown files and suggest helpful alternatives. AlexJS is able to flag the condescending language that we're looking for, as well as language that is maybe ableist, gendered, homofobic, racist, ... There are two different ways to use AlexJS for linting open source documentation. You can run npx-alex within the repository's directory. This allows you to run Alex without installing it to the project as a dependency. Or you can install it to the project, but maintainers typically need a lot of convincing before they add another dependency to their projects.
As tempting as it might be, you don't want to remove every instance that's flagged by AlexJS. Sometimes these terms can be present out of necessity, or as an attempt to be more welcoming, and we want to honor that. Before changing anything look at each instance and ask yourself the following: is it actually condescending or offensive? For instance: "simple" can be used to describe some kind of network protocol. You want to make sure you're not altering or removing terms that are essential for comprehension. You can also ask yourself: is it necessary. Many of these condescending terms are adverbs that can be removed without replacement. I found that to be especially true for terms like "just". It's rare for a term like "easy" to be intentionally condescending. Oftentimes writers use it to signal that maybe something isn't as intimidating as it sounds - which it great! If this is the case we want to be thinking about what the docs are trying to communicate, and want to replace with words that better represent that intention. If something is "easy" because it's quick to set up, maybe can say that instead. Or we can say how long we expect the setup to take.
Now that the work is done you can propose the changes with a pull request. Be sure to follow the project's contributing guidelines, and reference your initial issue. It can also help to include a summary of what you're trying to accomplish in this pull request, even if it's in the issue. Any agreements that were decided in the issue should also be present. And maybe some examples of terms you removed or replaced - that way everyone can learn!
I hope that some of you are inspired to make your first pull request, or help make your favorite projects' docs a little more inclusive. For anyone interested, I have a pinned post on my DEV channel with all the steps in more detail, plus more tangible examples: dev.to/carolstran.
Happy hacking!
Check contributing.today regularly for more interviews with contributors & maintainers, as well as online events to help you get involved in open source.
Top comments (0)