Inclusive Language

While writing documentation, we are directly speaking to thousands of people all around the globe. Thus, we must ensure our diverse audience can connect with our information.

1. Culturally inclusive language

Certain phrases and words are commonly used in specific regions of the world. Avoid using region-specific language in the documentation. Some examples of region-specific language are -

“It’s not rocket science” is commonly used in the USA, and non-US people might not be able to relate to it as intended.
Phrases written in regional languages instead of English.
“It’s a piece of cake” is commonly used in the USA, and non-US people might be unable to relate to it as intended.
Terms like "gypsy" is considered derogatory in Romani community, "eskimo" is considered offensive in artic community.
Terms like "tipping point" is considered offensive in African American cultures.

2. Gender neutral language

Some phrases and words target men or men/women specifically, resulting in other gender groups feeling left out while reading our documentation. Using only male pronouns also make women in technology feel excluded or overlooked. Similarly, we should also try to include nonbinary groups of people in our writing. Some examples of gender-neutral language are -

Using “they/them” instead of “his/him” or “she/her”.
Using “Hello everyone” instead of “Hello guys”.
Using “Chairperson” instead of “Chairman” or “Chairwoman”.
Using "people", "guests" or "folks" instead of "ladies and gentlemen".
Using "Mx" or "Ms" instead of using "Mr" or "Mrs".
Using "humankind" instead of "mankind".
Avoid using stereotypes such as linking "male" with "strength", "women" with "care work", or "male homosexuality" with "sensitivity".

3. Accessibility and Disability

The placement of the word “People” matters a lot when writing documentation. Using the word “People” in the beginning makes it more pleasant as the problem is not displayed initially. The phrasing of sentences should not be in a manner that depicts Ableism or discrimination against individuals with disabilities or the assumption that people with disabilities are inferior to those without disabilities.

Some examples of gender-neutral language are -

Using “People with a mental health condition” instead of “Mentally Unstable People”.
Using “Deaf” instead of “Person with deafness”.
Using "People with a disability" instead of "Disabled people".
Using "Wheelchair Users" instead of "Wheelchair bound".
Using "People experiencing homelessness" instead of "Homeless people"
Avoid using derogatory terms that refer to people with disabilities like "crazy", "retarded", spaz, and "lame".
Try using phrases like "overlook" or "ignore" instead of "turn a blind eye", or using "unheard" or "unnoticed" instead of saying "falling on deaf ears".

4. Slang-free language

While framing the documentation, we must ensure that we are not including any vulgar language, even if it is included indirectly in our work. We should be mindful of inadvertently including slang words within phrases that may have unintended or inappropriate connotations. Some examples include -

Using “simple” or “easy" instead of “no-brainer”.
Using "simple" or "straightforward" instead of "easy-peasy".
Avoid using any racist, sexist, or any discriminatory language like "stupid" or "retarted".
Use "easy" or "simple" instead of "piece of cake".
Using "excellent" or "impressive" instead of "dope"

5. Ageism-free language

When constructing the documentation, avoiding words or phrases that may disproportionately emphasize a specific age group is important, as this can make other age groups feel excluded. Some examples include -

Avoid mentioning the exact age like “60 years” old.
Using "experienced" instead of "old-timer"
Avoid phrases like "you are too old to understand" or "you are too young to understand"
Using “lively” instead of “young”.
Avoid making assumptions about a person's abilities or interests based on their age, like assuming an older adult will not be tech-savvy.

6. Knowledge level assumption-free language

While building the documentation, we should always ensure that we don’t presume the knowledge level of the readers. Assuming that our readers are highly skilled or have advanced experience, we might inadvertently skip explaining or linking some important concepts. Also, we should avoid labelling some steps as “easy” because this might make some readers question their technical abilities. Some examples include -

Using “fixing the navbar is good to start with” instead of “fixing the navbar is very easy”.
Linking complex topics that most of our audience won’t understand.
Avoid phrases like "As you already know, the Fourier series is a mathematical method used to represent periodic functions."
Avoid including phrases like "You're probably familiar with the concept of compound interest so that I won't go into too much detail about it."

On this page