Writing Inclusive Documentation¶
Write using inclusive language, word choice, and examples.
We write our eLearning with inclusivity and diversity in mind. This page is not an exhaustive reference, but describes some general guidelines and examples that illustrate some best practices to follow.
Avoid ableist language¶
When trying to achieve a friendly and conversational tone, problematic ableist language may slip in. This can come in the form of figures of speech and other turns of phrase. Be sensitive to your word choice, especially when aiming for an informal tone. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. Choose alternative words depending on the context. For example:
There are some crazy outliers in the data.
There are some baffling outliers in the data.
It cripples the service, and users will need to wait until the queue clears.
It slows down the service, and users will need to wait until the queue clears.
Avoid unnecessarily gendered language¶
In addition to being mindful of the pronouns used in narrative examples, be sensitive to other possible sources of gendered language.
Equipment installation and setup takes around 16 man-hours to complete.
Equipment installation takes around 16 person-hours to complete.
This API might be just what your globally conscious company needs to help all of mankind.
This API might be just what your globally conscious company needs to help all of humanity.
Write diverse and inclusive examples¶
Use diverse names, genders, and locations in examples. Keep the following advice in mind:
- Follow our gender-neutral pronoun guidance.
- Avoid being too culturally specific to the US. Be mindful when referring to specific holidays, cultural practices, sports, figures of speech, etc. Being sensitive here also supports writing for a global audience.
- Take care to choose a diverse set of names to help examples reflect the real world diversity of our audience.