Writing inclusive documentation

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: 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:

Envoyer des commentaires concernant…

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide
https://developers.google.com/style/inclusive-documentation?hl=fr
developers.google.com
crawl=CC-MAIN-2019-09
46417
application/http; msgtype=response
sha1:NGL4NCE6MSZBS6VKQQBHCMQ5Z2LN5VMF
<urn:uuid:9eb91a96-d0bd-49d7-b162-1f022aa20532>
2019-02-22T14:08:32Z
172.217.164.142
text/html
sha1:Z5NLY7E4VEJS66OHEQVUHGYX3JJ6INTF
<urn:uuid:08ea6117-c9ef-41e7-955f-f51a5f022060>
https://developers.google.com/style/inclusive-documentation?hl=fr
response
<urn:uuid:38642323-c382-482a-b35d-5a1463693d8b>
isPartOf: CC-MAIN-2019-09
publisher: Common Crawl
description: Wide crawl of the web for February 2019
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-171-229-147.ec2.internal
software: Apache Nutch 1.15 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 0.11-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/