Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Words Matter in Documentation to Build Better User Experience

Words Matter in Documentation to Build Better User Experience

This item in japanese


The language that we use in our products or documentation can make people feel unwelcome or hurt people. We can choose words that are precise, not dependent on complex metaphors, and convey messages without negative connotations.

Eliane Pereira and Josip Vilicic, both technical writers, spoke about promoting inclusion in documentation at OOP 2022.

Pereira spoke about metaphor terms that we can find in product documentation that have a negative connotation for a group of people, even though they may seem harmless to some of us:

Examples are using "blacklist" to denote lack of access or describing non-white or non-Western things as "exotic". Other examples are using ableist terms that refer to disabilities, such as "blind spot" instead of "gap", because it refers to someone’s characteristics as something negative, making them feel unwilling to use or consume such a product or project.

According to Vilicic, people feel unwelcome when they feel excluded. If documentation keeps referring to the audience as "he," like in "we like to give the customer what he wants," then anyone in the audience who is not a man would rightfully feel either purposely excluded, or not even considered. Language can be hurtful when it’s insensitive to the audience, such as using racist terms, or outdated terms, he said.

Pereira suggested using words that do not have a metaphor behind them:

If you choose literal words, you are able to express very clearly what you want to say. For example, when discussing servers, the "master/slave" scenario could be safely replaced with "source/replica". With this, we are able to consistently choose words and even provide options that could fit your organization better.

Vilicic explained that the words that have negative connotations are usually complicated metaphors, and often, these are difficult to translate into other languages:

Instead of asking your audience to process a metaphor, to then apply it to another unrelated concept, I think it would be easier to use more precise language.

InfoQ interviewed Eliane Pereira and Josip Vilicic about inclusion in documentation.

InfoQ: Are people aware of how the words they use may be perceived or the impact that they might have?

Josip Vilicic: We have noticed that very few people purposely hope to exclude others with their language, so they are often unaware of the negative impact of their words.

Eliane Pereira: "Whitelist" and "Blacklist" are understood as a way to inform what is allowed and what is not. For a person of color, this perception can be different. That is why we believe that it is a matter of talking to people about harmful language. By bringing awareness, we can make people think about it, notice patterns and start their changes. "Allowlist" and "denylist" could be used without any issue and no one would miss their meaning.

InfoQ: What can be done to raise awareness of possible exclusion through language?

Vilicic: As communicators, it’s up to us to educate ourselves and help our peers do better. When we hear someone inadvertently use an offensive term, we can "call them in" (as opposed to "call them out" in a public, shaming way) where we approach the person in private and sensitively talk to them: "Hey, when you used the term ____, were you aware that many people in the ____ community find that term offensive?"

We’ve had success with this technique: it allows for good dialogue because no one is put in a defensive position, and we help each other grow towards being more compassionate with one another.

InfoQ: If readers want to learn more about inclusive language, where can they go?

Vilicic: Since inclusive language is dynamic and responding to communities in real time, I would suggest looking at internet resources. A good one is the American Psychological Association Inclusive Language Guidelines, which has a list of inclusive language concepts and terms.

Pereira: For those who are interested in learning more about Inclusive language: if you are looking for ways on how to be an ally, the repository Better allies propose actions to create inclusive, engaging workplaces. For word replacement, I recommend the Inclusive Naming Initiative and inclusive language.

About the Author

Rate this Article