loading...
Meeshkan

How to remove condescending language from documentation

carolstran profile image Carolyn Stransky Originally published at meeshkan.com Updated on ・6 min read

Inspired by a tweet from Anjana Vakil, I set a goal for Hacktoberfest 2019 to remove words like simple, easy or any other variation from open-source documentation.

Over the next month, I submitted over a dozen pull requests to projects like Jest, Cypress, Storybook and even some of our own repositories at Meeshkan (🙈). This initiative also inspired pull requests to webpack, Tailwind CSS and React Native. The React Native team even took it a step further and linted all 56 versions of their documentation in 6 days with help from 30 outside contributors.

Throughout this process, I learned a lot about the value of creating more inclusive docs and the practicalities of making it happen. So I've compiled these learnings into a guide!

Table of Contents

Why focus on condescending language?

Rick Hanlon from the React Native team summed this up well in a recent tweet:

When we say things are "easy" or "simple" then it makes people feel inadequate or otherwise hurt if they don't immediately understand it.

Language is subjective - a simple concept for one person isn't always simple for another. By banning condescending terms from our documentation, we're taking a proactive step towards making our material more inclusive.

If you're interested or want more information on this topic, I'd highly recommend watching Jim Fisher's Don't Say Simply talk from Write the Docs Prague 2018.

What is condescending language?

Some examples of language considered condescending includes...

simply
easy
basically
clearly
everyone knows
just
obviously
of course

If you're interested in why these words are considered condescending, retext-equality (a plugin that checks for insensitive language) has a full list with explanatory notes.

As promised, a guide!

⚠️ Prerequisites:

✅ Steps:

  1. Open an issue describing your mission
  2. Use the alex.js linter to flag condescending terms
  3. Remove or replace instances of condescending language
  4. Create a pull request with your proposed changes

1. Open an issue describing your mission

If you aren't a regular contributor to the project, I'd suggest opening an issue before starting any work. If you're new to open source, GitHub has step-by-step documentation on creating an issue.

This step isn't always necessary, but it does give you the opportunity to describe the value a change like this will bring and see if the maintainers are open to this type of change (not all of them are).

On the other hand, this allows maintainers to suggest a preferred format for the changes - for example, submitting one pull request for every section instead of all at once - and let you know if they have any existing language linters you can work with or modify.

Reference: An issue I opened on the Cucumber Documentation.

2. Use the alex.js linter to flag condescending terms

You've gotten the OK from the maintainers. You've forked and cloned the repository. Now, you need to identify condescending terms to potentially remove.

You could manually search for terms within the documentation... but that can be tedious. Plus then you're more likely to miss variations (for example, easily instead of easy) or words you weren't aware were offensive. So to help, I'd suggest using alex.js.

alex.js is an open-source language linter designed to catch polarizing writing in Markdown files and suggest helpful alternatives. Because its rules are rooted in retext-equality, alex is able to flag the condescending language we're looking to remove as well as language that is ableist, gendered, homophobic, racist and anything else that's better left out of our documentation.

To use alex for linting open source docs, there are two approaches you could take:

Run npx alex within the repo directories

Using npx allows you to run the linter without installing alex as a dependency to the project. I'd suggest this as a first step because, speaking from experience, asking maintainers to add an additional dependency will take much more convincing than changing the wording in their docs.

To run alex locally, use your terminal to move into the directories containing the Markdown files you want to lint. In many projects, this folder will be called docs/. Once you're there, run the following command:

npx alex

You can also lint specific files by adding the file name to the end of the command. In this example, we're checking our project's README.md file:

npx alex README.md

Install alex as a dependency within the project

As mentioned, this one might take more convincing upfront - but if a project is dedicated to keeping this type of language out of their documentation, then this a proactive step they can take.

To set up alex in a project's workflow, you can follow this step-by-step tutorial. Because this requires additional configuration, a maintainer may ask you to tackle this in a separate pull request.

3. Remove or replace instances of condescending language

As tempting as it is, you don't want to remove every instance that is flagged by alex or your own search. Because, sometimes, these terms can be present out of necessity or as an attempt to be more welcoming.

Before changing anything, take a look at each instance and ask the following...

Is it actually condescending or offensive?

For instance, words like simple can be used to describe a specific type of network protocol or alex will flag terms like host which could refer to network hosts. So you want to be sure that you aren't removing or altering terms that are essential for comprehension.

Is it necessary?

In many cases, these condescending terms are adverbs that can be removed without any replacement. I've found that this is especially true for the words just and of course.

If it's necessary, what is it trying to say?

With documentation, it's rare for terms like easy to be intentionally condescending. Often times, writers use them to show that something isn't as intimidating as it sounds. If this is the case, think about what the docs are trying to communicate and replace the condescending language with word choices that better represent the intention.

If you're struggling to find alternatives, Jim Fisher has some suggestions:

  • Be specific: Maybe it's easy because it's quick to set up, doesn't require much typing or has few moving parts.
  • Be comparative: Something is smaller than something else. Compared to another product, your product requires less custom configuration.
  • Be absolute: It takes 5 lines of code to integrate this library. There are two form fields required.
  • Show, don't tell: Instead of using time as an indicator for how easy something is, create a video.

4. Create a pull request with your proposed changes

Now that the work is done, you can propose your changes with a pull request. If you're new to open source, GitHub has step-by-step documentation on creating a pull request.

Be sure to follow the project's contributing guidelines and reference your original issue (if you opened one). Even if you're referencing an issue, it helps to include:

  • A summary of what you're trying to accomplish with this pull request
  • Any agreements that were decided in the issue
  • Examples of the terms you removed or replaced

This way, if another maintainer reviews your changes, they can gain context without having to read the entire issue and discussion.

Reference: A pull request I created for Prisma.

Finally, a thank you 🎉

Thanks for taking the time to read this guide and taking steps towards more inclusive open-source documentation! We need more wonderful, caring people like you. This effort also requires awareness. So I'd encourage you to share your journey with your colleagues, friends, Twitter followers - whoever will listen.

Discussion

pic
Editor guide
Collapse
syntaxseed profile image
SyntaxSeed (Sherri W)

Embarrassed to say I've never thought of this before. I will be reviewing the docs for my OSS projects because of this article. Thank you.

Collapse
themanthel3g3nd profile image
Info Comment marked as low quality/non-constructive by the community. View code of conduct
Tyrone

You've never thought of it because it's silly. Devs have better things to do than worry about "condescending language".

Collapse
syntaxseed profile image
SyntaxSeed (Sherri W)

It's literally the foundation of what we do: create things for users. If you create libraries & tools that have documentation... that documentation is also something we create for the users.

And much like we try to be aware of tuning our creations to the accessibility, aesthetics, demographics, & skill levels of our users... a few simple adjustments to consider the confidence level of our users & not degrade them unintentionally is as valuable as any other usability feature.

Happy users = successful development, no matter how you ensure that happiness.

Collapse
scottshipp profile image
scottshipp

Being respectful of differing viewpoints and experiences is one of the values at DEV. Even if something is "silly" to you, that doesn't mean it is for someone else. Comments like that also don't contribute anything to the conversation but close down conversation instead. It's better to follow the old adage, if you can't say anything nice don't say anything at all.

Collapse
pinotattari profile image
Riccardo Bernardini

I agree.

Honestly, I never considered words like "easy", etc. as "condescending," neither as writer nor as reader. It sounds like a variation on "mental fun on language"

Collapse
chetbox profile image
Chetan Padia

"Silly" is far more condescending than any of the language mentioned in this article. Please think about the language you use and try to empathise.

Thanks for the excellent post, Carolyn.

Thread Thread
themanthel3g3nd profile image
Info Comment marked as low quality/non-constructive by the community. View code of conduct
Tyrone

Please don't attack me. Let me be me. If you don't like it - tough. Ok, Gupta.

Collapse
s_aitchison profile image
Suzanne Aitchison (she/her)

I love this and thank you for writing about your approach - it's really useful!

It's so easy to accidentally add this kind of language to docs and tutorials and I really like the idea of adding a linter for it to help catch it all 👍

Collapse
tehunk profile image
TaeHun

Perhaps "condescending" is not the best word to describe such expressions, but I can relate to the sentiment. It has annoyed me many times when documentation claims it's "easy", but there was an "unclear" assumption that didn't make things easy in practice. In general, one should strive to convey only reproducible facts in documentation without subjective/unnecessary expressions. If you claim something is "simple and easy" in the documentation, show me the evidence. I've seen tutorials and docs with phrases like "just type xxx". Do you really need that extra word "just" there? How does that improve readability or change meaning? Doc is not an essay or pitch.

Collapse
gido profile image
Gilles Doge

The Symfony documentation use the term "belittling". Maybe it fit you best: "Avoid belittling words", github.com/symfony/symfony-docs/bl...

Collapse
matthewtole profile image
Matthew Tole

This is a great article, and I appreciate your efforts to push open source projects to be more inclusive in their documentation.

I'm curious about situations where you've encountered resistance from maintainers / other contributors, and how you've managed to convince them (or not) of the benefits of these changes?

Collapse
andrewbrown profile image
Andrew Brown 🇨🇦

I would omit adjectives because they are superfluous to technical documentation.
I never thought about how they affected tonality.

Before Grammarly reported tonality I had no idea what tone my writing came across since I write in draconian style treating every textbox as documentation.

Collapse
passwort12345 profile image
Tilman Hausherr

Avoid using adjectives is an argument I'd accept somewhat. I hate when it is done in journalism, because this mixes content and comment.

Collapse
andrewbrown profile image
Andrew Brown 🇨🇦

I had a journalism class in college over a decade ago for copywriting and they taught you to avoid adjectives. So this certainly where it started for me.

Collapse
almenon profile image
Almenon
simply
easy
basically
clearly
everyone knows
just
obviously
of course

"everyone knows": Everybody knows this phrase is clearly false. See what I did there? :P But seriously, I can't think of a single good reason to use this phrase in documentation. Removing it is a-okay in my book.

"just", "obviously", "of course", and "clearly": They do have slight negative connotations. But whether they could actually be construed as condescending or not highly depends on their usage. I'm not entirely opposed to switching these out but I'm somewhat skeptical.

"simply", "easy", "basically": These are very common words and are not inherently condescending. Replacing all uses of these is going too far. Effort in helping newcomers and marginalized groups would be better spent elsewhere.

Collapse
ben profile image
Ben Halpern

This is fabulously written

Collapse
discdiver profile image
Jeff Hale

This is great and so important! Thank you so much for your work! Nothing is worse that someone telling you how simple something is and getting stuck on it.

Collapse
u8nc profile image
MiAn

I suspect those that use this type of language are seeking an alternative to dry technical descriptions and are seeking to make it more conversational and less alarming to a new user.

That argument may have held last decade, but most people have had enough exposure to technology that they just want the facts without all the verboseness.

Since Open Source is the context you are raising it in here, many such software tries to emulate more professional commercial offerings with the perhaps false premise new users haven't gone through their learning curves. That means the documentation writer ( whether the coder or UI designer or team lead ) assumes no prior knowledge of that industry sector in which it is used. So they have a choice, make it terse and clinical ( Documentation is a Legal Instrument after all ), or try to make it friendly in some way.

The problem is the "some way" the they choose. Carolyn has raised a valuable viewpoint of one such "some" way. I've never liked using used those terms, but not for the reasons the OP has raised. I've never seen them as condescending, but then I'm an arrogant old such-and such and a bit of a little Hitler when it comes to getting people to do what I want.

I can speak a few languages and am learning a few more from Arabic to various Asian ones, and many of those don't include incidental and decorative words that the romance languages do. ( French German English Italian Spanish etc. ) Quite often these words have come about to make phrases "roll off the tongue a lot easier, and give the speakers brain time to engage in what to say next, or from the listeners point of view time to assimilate what they've heard.

And that's where the problem arises. People try to put on paper what belongs to speech. It very rarely works. It's like trying to cross pollinate a hybrid tree from the Conifer group with a Hardwood. If its not condescending its plain awkward. Leave it out.

Then there's a separate minefield when these have to be translated, either in word-for-word or thought-for-thought.

I tried once to make a humorous interplay between the unsaid instructor that is the manual and the learner as Preying Mantiss Mastah and Humble Glasshoppah. I decided that humour is too dangerous, even before going cross cultural with it.

What worked in various places was to be a bit verbose and explain the reason for the prominence of the UI being as it was with other controls hidden behind a tab, and implied therein was the "just simply" without being said.

It's a skill, and I think there are better people than me with some of the docs I've read.
Thanks again for raising it.

Collapse
john_horner1 profile image
john_horner

This is a really interesting idea, thanks for that. It had never occurred to me before.

I do worry that some dry humour will be lost, as in this classic from perldoc:

[substr()] return value is based at 0 (or whatever you've set the $[ variable to--but don't do that).

But it's a small price to pay.

Collapse
dkamer profile image
David Kamer

I don't know if "just" is in the same league as the other words.

The word "simply" definitely is condescending, and "just" can be used that way, but "just" can be used in many natural ways.

With that said, it usually isn't necessary.

Collapse
dkamer profile image
David Kamer

In my opinion, just is often used in an opposite way to condescension. "Just do x" is often used to assume you would do a more difficult task in the easier task's place. So, for instance, if you were to use an automation tool, I'd likely describe the last instruction on how to automate it as something like, "Just click the button and everything is running!"

"Simply", however, usually isn't used this way.

Collapse
cescquintero profile image
Francisco Quintero 🇨🇴

Great to know. I might have used this kind of words for some docs. Not that I did on purpose but now I'm aware of their implications 😃

Collapse
cneude_matthieu profile image
Matthieu Cneude

Nice article! I totally agree with everything. I think too that this kind of language should not be used while speaking either, for the same reasons.

I wrote a similar article in that sense some years ago, if somebody is interested: thevaluable.dev/development-easy-j...

Collapse
codemouse92 profile image
Jason C. McDonald

This article inspired me to write a "Word/Phrase Hit List ☠️" for editing my upcoming tech book. I'm scrubbing out as many instances of the following as possible and reasonable:

  • "of course"
  • "obvious"/"obviously"
  • "naturally"
  • "just"
  • "merely"
  • "only"
  • "simple"/"simply"
  • "easy"/"easily"
  • "basic"/"basically"
  • "clear"/"clearly"

There are rare exceptions, but in general, these words die. ;)

Collapse
davep profile image
Dave Pearson

Thanks for this. It's something I've tried to be mindful of more recently, but is personally difficult to really keep on top of. The linting approach is going to be really helpful.

Collapse
mwendarapho profile image
mwendarapho

Interesting

Collapse
idered profile image
Kasper Mikiewicz

You can also use npmjs.com/package/cspell and define invalid words, plus it will spell check your code

Collapse
zooloo2014 profile image
Brent Engelbrecht

This is a fantastic initiative.
Hopefully it will also be a start towards software development practitioners reflecting on all their jerk-like behaviours.

Collapse
scottshipp profile image
scottshipp

This is a great initiative and I'm so glad that our industry is embracing it!

Collapse
wlcdesigns profile image
wLc

Add "naive" to that list.

Collapse
jbristow profile image
Jon Bristow

I'd put this one in the WARN pile, but it's a math term so YMMV. (Naive is a [sortof] opposite of axiomatic)

So if I saw it in documentation ("Users may naively try to...") I'd want it gone, but if I saw it in reference to a "naive sort" or "naive bayes" or "naive set theory" I'd want it to stay.

That caveat aside, you have to be really smug to use naive in that "conversational" style in your docs. (Not that I haven't seen it... but yeah... it's a pretty high-fidelity flag)

Collapse
passwort12345 profile image
Tilman Hausherr

Sigh... The argument made here is familiar from the concept of micro-agressions. These things don't bother anyone (I've heard "where do you come from" hundreds of times, both in and outside my country and it never made me angry), but as soon as people get taught that it is a micro-agression and believe in it, it works as such. The same applies with "simple". I'm frustrated when I can't get something done, not because these words are used. (Besides, most people don't read the documentation anyway) But now that I've read that it is condescending, the word gets a new meaning, despite that the author never intended to be condescending, i.e. people who believe in the concept of micro-agressions might actually feel "unconfortable" or "unsafe" when seeing these words, starting from the minute they read this article.

Collapse
256hz profile image
Abe Dolinger

It sounds like you think microaggressions are invented by people who have nothing better to do than feel victimized. If I'm reading that wrong, I apologize, but I assure you that it's not the case. I found this blog on the subject very helpful: microaggressions.com

It's a mistake to project yourself onto everyone else, and assume they should feel as you do. If a question offends someone, try to put yourself in their shoes. Don't tell them what they feel is wrong or doesn't matter.

Also, lots and lots of people read the docs. The only reason not to is if they're not good or not there. Docs are great!

Collapse
passwort12345 profile image
Tilman Hausherr

Indeed, there is a growing culture about feeling victimized (instead of getting more resilient), and yes, the original twitter author (who projects that concept on everyone else) assumes people should feel that way, i.e. should feel "stupid" just because something doesn't work when it is "easy". Over 50% of IT is stuff not working, so frustration is always there - for a short time. And in many cases, people didn't bother to read the docs.

My favorite source on microagressions is this analysis. Watch it till the end or I will feel uncomfortable!
youtube.com/watch?v=cir65niCkMM

But yeah, I'll probably remove some of these words from our documentation when I have the time, per my other argument (no adjectives in journalism) and to protect the project.

Collapse
khepu profile image
Info Comment marked as low quality/non-constructive by the community. View code of conduct
Khepu

This is the dumbest thing I've seen in a while. Condescending language? Really? How easily are your feelings hurt that you are trying to make people change the way they express themselves? You are completely missing the point of documentation which is not to pat you on the back but to guide you and provide information. Sometimes I feel like people are looking for excuses to just post an article but this one made me completely livid.

Collapse
moopet profile image
Ben Sinclair

We're trying to be a friendly, helpful community, and in that light, your comment is not constructive.

I think this is a very useful post. People, myself included, genuinely feel put off when we try to follow documentation that suggests we should be able to do something, and that it's our fault when we fail. It might be our fault, but it might also be down to missing or outdated documentation, and I'm sure you've felt some measure of frustration with scrappy documentation in the past?

Nobody likes to feel like an impostor (to crowbar that word in), but that's sometimes the result of telling people a task is "easy" when it's not.

Collapse
khepu profile image
Info Comment marked as low quality/non-constructive by the community. View code of conduct
Khepu

Here is something constructive, man up.

Thread Thread
marcellothearcane profile image
marcellothearcane

Could you take a step back and consider why this makes you 'completely livid'? You are perfectly entitled to consider this suggestion beneath you, and other people are perfectly entitled to not agree with you.

I suggest you try to calm down and look at this more maturely. I don't know how this such a significant issue to make you 'completely livid' - you don't have to follow the suggestion if you don't want to, and if other people start considering how they write documentation differently, what is it to you?

Thread Thread
mburszley profile image
Maximilian Burszley

a significant issue

Is it really, though?

Collapse
syntaxseed profile image
SyntaxSeed (Sherri W)

I cannot fathom the people who take issue with others looking for ways to be nice.

Don't want to apply this to your docs? Then don't.

But being angry that some of us like this idea, is a waste of your time taken to type your comment.

Collapse
256hz profile image
Abe Dolinger

What's so funny about this viewpoint is that it demands that it be pandered to by expressing anger. "No one should try to be nice in this way because it makes me mad!" That's not going to help anything.

Also, your goals are exactly the same as the ones you're angry about. These editors are also trying to use docs to guide you and provide information. They advance the argument that a neutral, non-condescending tone is a better way to do that. Is that worth getting livid over? Why such anger?

Collapse
0xicl33n profile image
0xicl33n

I strongly agree with you