Skip to content

Writing Inclusive Documentation

Summary

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:

Not recommended

There are some crazy outliers in the data.

recommended

There are some baffling outliers in the data.

Not recommended

It cripples the service, and users will need to wait until the queue clears.

recommended

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.

Not recommended

Equipment installation and setup takes around 16 man-hours to complete.

recommended

Equipment installation takes around 16 person-hours to complete.

Not recommended

This API might be just what your globally conscious company needs to help all of mankind.

recommended

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:

Comments