Writing inclusive documentation

Key Point: Write using inclusive language, word
choice, and examples.

We write our developer documentation 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: Before launch, give
everything a final sanity-check.

Recommended: Before launch, give
everything a final check for completeness and clarity.

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,
causing a poor user experience until the queue clears.

Recommended: It slows down the service,
causing a poor user experience until the queue clears.

Not recommended: Replace the
dummy variable in this example
with the appropriate variable.

Recommended: Replace the placeholder
variable in this example with the appropriate variable.

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.

Write diverse and inclusive examples

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.

When writing about older adults, avoid terms and figures of speech such
as the elderly, the aged, seniors,
senior citizens, 80 years young. Instead, use terms such as
older adults, aging population, or mention the person's
relative age or relationship to the other people in your example when those
details are relevant.

Write about features and users in inclusive ways

Avoid referring to people in divisive ways. For example, instead of referring
to people as "native speakers" or "non-native speakers" of English, consider
whether or not your document needs to discuss this at all, and revise in order
to discuss the feature in terms that are relevant to anyone regardless of what
languages they know.

Avoid using socially-charged terms for technical concepts where possible. For
example, avoid terms such as blacklist
and
first-class
citizen, even though these terms may still be widely used. Instead of
first-class, consider other terms such as: core feature,
built-in, top-level. Choose the best term for your context.

Avoid graphically violent or harmful terms. For example, avoid using the
term STONITH; instead, describe
the process used to stop an errant node in context using more specific terms.

If it's unavoidable and you must mention a violent or harmful term such as
STONITH, mention it once when you first explain the relevant
feature, but phrase it in a way that de-emphasizes the term. For example:

Recommended: This might require you to fence
failed nodes.

Sometimes okay: This might require you to
fence failed nodes (sometimes referred to as STONITH).

Avoid bias and harm when discussing
disability and accessibility

Many developers create products with accessibility and disability in mind.
When documenting these features, and when writing about people with
disabilities or about accessibility, work to eliminate unintentional bias and
harm. Take the time to educate yourself about the ways the communities you're
writing about prefer to be identified and described before writing about them in
your documentation.

Some general guidelines in this area include:

Don't describe people without disabilities as "normal" or "healthy". This
contributes to othering and alienation of people with disabilities by implying
they are abnormal or sick. Instead, use terms such as: nondisabled person,
sighted person, hearing person,
person without disabilities, neurotypical person.

Research the ways the people in the communities you're writing about
prefer to be identified and use the terms they prefer. In many cases, avoid
terms that remove personhood, or that define people by their disability. For
example, avoid terms such as: the disabled, a quadriplegic.
Instead, use terms such as: people with disabilities;
a quadriplegic person. However, many members of some communities prefer
"identity-first language"; for example, that preference is common in autistic,
blind, and Deaf communities. Capitalization of identities also may vary. (For example, visit
Identity First Autistic
and
Self-Identification
in the Deaf Community for some perspectives.) Whenever possible, research
and choose terms that respect the ways people in the communities
identify.

Avoid terms that reflect or project feelings and judgements about a
person's disability, such as: victim of, suffering from,
wheelchair-bound.
Instead, use neutral terms such as: experiencing,
living with, uses a wheelchair.