incl-001 should GuidesAPI docsMarketingBlog Use singular they as the default gender-neutral pronoun for a generic person whose gender is unknown or unspecified. Don’t use he or she, he/she, or alternating gendered pronouns across examples.
Inclusive content
Inclusive content describes people and systems accurately without bias, stereotypes, or loaded metaphors. Use this page when you choose pronouns and terminology or create people and scenarios for examples and images.
For guidance on content and interfaces that work with assistive technologies, see the accessibility topic.
Use singular they for a generic person
Section titled “Use singular they for a generic person”Examples
- ✓ When a developer rotates their API keys, notify them by email.
- ✗ When a developer rotates his or her API keys, notify him or her by email.
Rationale
Singular they avoids assuming a person’s gender and is less cumbersome than alternatives such as he or she.
Use a person’s stated pronouns
Section titled “Use a person’s stated pronouns”incl-002 should GuidesAPI docsMarketingBlog Use the pronouns that a specific person uses. Don’t infer them from the person’s name or appearance. If you don’t know a person’s pronouns, use they or rewrite to avoid the pronoun.
Examples
- ✓ Sam Rivera presented the roadmap, and she took questions afterward. (Sam uses she.)
- ✗ Sam Rivera presented the roadmap, and he took questions afterward. (Pronoun guessed from the name.)
Rationale
A person’s stated pronouns are more accurate than an assumption based on their name or appearance.
Use gender-neutral job titles
Section titled “Use gender-neutral job titles”incl-003 should GuidesAPI docsMarketingBlog Replace gendered job titles and general terms with gender-neutral equivalents, such as chair for chairman and person-hours for man-hours.
Examples
- ✓ Estimate 6 person-hours for the migration.
- ✗ Estimate 6 man-hours for the migration.
Rationale
Gendered titles can imply that only one gender holds the role. A neutral title names the work without that implication.
Avoid ableist language
Section titled “Avoid ableist language”incl-004 should GuidesAPI docsMarketingBlog Avoid ableist language, including crazy, insane, sanity check, blind to, cripple, and dumb. Use a neutral term that describes the intended meaning.
Examples
- ✓ Run a validation check on the configuration before deployment.
- ✗ Run a sanity check on the configuration before deployment.
Rationale
Ableist figures of speech use disability as a negative quality or an insult. A literal description also identifies the actual condition or action.
Don’t frame disability as suffering
Section titled “Don’t frame disability as suffering”incl-011 should GuidesAPI docsMarketingBlog Use neutral language about disability. Don’t use terms that imply pity, such as suffering from, victim of, stricken with, or wheelchair-bound.
Examples
- ✓ The voice-control feature helps users with limited mobility.
- ✗ The voice-control feature helps users suffering from limited mobility.
Rationale
Terms such as suffering from define disability as a tragedy rather than describing the person’s situation. Neutral wording states the relevant fact without adding pity.
Don’t call nondisabled people normal
Section titled “Don’t call nondisabled people normal”incl-012 should GuidesAPI docsMarketingBlog Don’t describe people without disabilities as normal or healthy. Use nondisabled person, person without a disability, neurotypical person, or another accurate term.
Examples
- ✓ Test the flow with both screen-reader users and sighted users.
- ✗ Test the flow with both screen-reader users and normal users.
Rationale
Using normal as the contrast to disabled defines disability as abnormal. Name each group accurately instead.
Person-first and identity-first language
Section titled “Person-first and identity-first language”incl-013 should GuidesAPI docsMarketingBlog Use person-first language, such as people with disabilities, when a person or community has not stated a preference. Some communities, including autistic, Deaf, and blind people, prefer identity-first language. Research and follow a stated preference instead of applying one form universally.
Examples
- ✓ The setting helps people with disabilities navigate the application.
- ✗ The setting helps the disabled navigate the application.
- ✓ The captions setting helps deaf and hard of hearing people follow the video.
- ✗ The captions setting helps people with deafness follow the video.
Rationale
Person-first language avoids defining people by a disability when their preference is unknown. Language preferences differ among communities and individuals, and following a stated preference is more accurate and respectful than applying one formula to everyone.
Don’t frame disability as inspiring
Section titled “Don’t frame disability as inspiring”incl-016 should GuidesAPI docsMarketingBlog Don’t call a person inspiring, brave, or courageous only because they have a disability. Don’t frame disability as something to overcome.
Examples
- ✓ The engineer rebuilt the screen-reader test suite.
- ✗ Despite her disability, the engineer bravely rebuilt the screen-reader test suite.
Rationale
Praise the person’s work or achievement, not the existence of their disability. Praising disability itself shifts attention from the person’s work to the observer’s feelings.
Avoid disability euphemisms
Section titled “Avoid disability euphemisms”incl-022 should GuidesAPI docsMarketingBlog Avoid euphemistic or patronizing disability terms such as physically challenged, special, differently abled, or handi-capable.
Examples
- ✓ The high-contrast theme supports users with low vision.
- ✗ The high-contrast theme supports differently abled users.
Rationale
Euphemisms can obscure the specific disability and sound patronizing. Use the term that the person or community prefers.
Avoid violent figurative language
Section titled “Avoid violent figurative language”incl-005 should GuidesAPI docsMarketingBlog Avoid violent figurative language in technical content. When a term such as hang, kill, or STONITH isn’t required by code, an interface, or an established technical name, use a specific neutral alternative.
Examples
- ✓ Stop the process if it becomes unresponsive.
- ✗ Kill the process if it hangs.
Rationale
A violent metaphor can distract readers and hide the action or state being described. A neutral technical term is more precise when the product language doesn’t require the original term.
Replace the terms master and slave
Section titled “Replace the terms master and slave”incl-006 should GuidesAPI docsMarketingBlog Replace master and slave with relationship-specific alternatives such as primary and replica, controller and agent, or parent and subordinate.
Examples
- ✓ The primary node replicates data to two replica nodes.
- ✗ The master node replicates data to two slave nodes.
Rationale
The terms derive from slavery and don’t describe the technical relationship precisely. Names such as primary and replica describe each role directly.
Replace blacklist and whitelist
Section titled “Replace blacklist and whitelist”incl-007 should GuidesAPI docsMarketingBlog Replace blacklist and whitelist with blocklist and allowlist, or name the action without either term.
Examples
- ✓ Add trusted IP addresses to the allowlist.
- ✗ Add trusted IP addresses to the whitelist.
Rationale
The color metaphor assigns negative and positive meanings to black and white. Blocklist and allowlist describe the behavior directly.
Introduce legacy terms once
Section titled “Introduce legacy terms once”incl-014 should GuidesAPI docsMarketingBlog When an established non-inclusive term must be introduced because it appears in code or common industry usage, introduce it once in parentheses and in code font when applicable. Use the preferred term throughout the rest of the document.
Examples
- ✓ Protect the primary branch (named
masterin older repositories). The primary branch then requires review before merges. - ✗ Protect the
masterbranch. Themasterbranch then requires review before merges.
Rationale
Introducing an unavoidable legacy term once preserves searchability and helps readers recognize it. Using the preferred term afterward avoids unnecessary repetition.
Don’t use color as a metaphor
Section titled “Don’t use color as a metaphor”incl-015 should GuidesAPI docsMarketingBlog Don’t use color as a metaphor for positive or negative qualities, as in black hat, white hat, or red team. Use color words only to describe actual colors.
Examples
- ✓ Invite an ethical hacker to test the endpoint.
- ✗ Invite a white-hat hacker to test the endpoint.
Rationale
Using black for bad and white for good assigns value to colors. Describe the behavior or role instead.
Avoid appropriative slang and profanity
Section titled “Avoid appropriative slang and profanity”incl-019 should GuidesAPI docsMarketingBlog Don’t use cultural or religious terms as casual slang, such as spirit animal. Don’t use profane or derogatory terms.
Examples
- ✓ This debugging script is my preferred tool.
- ✗ This debugging script is my spirit animal.
Rationale
Using a cultural or religious term as slang strips it of its original context and can disrespect the culture or religion it comes from. Profanity and derogatory terms can exclude or insult readers.
Avoid the pets and cattle metaphor
Section titled “Avoid the pets and cattle metaphor”incl-020 should GuidesAPI docsMarketingBlog Don’t use the pets and cattle metaphor to contrast individually managed systems with interchangeable infrastructure.
Examples
- ✓ Treat your servers as identical, replaceable units.
- ✗ Treat your servers like cattle, not pets.
Rationale
The metaphor asks readers to infer operational differences from a comparison with animals. Describe the replacement, identity, or state-management behavior directly.
Avoid socially charged technical terms
Section titled “Avoid socially charged technical terms”incl-023 should GuidesAPI docsMarketingBlog Avoid technical terms with socially charged meanings, such as native feature and first-class citizen, when a neutral description is more precise.
Examples
- ✓ Webhooks are fully supported across the platform.
- ✗ Webhooks are first-class citizens in the platform.
Rationale
These phrases borrow language about nationality or social rank without describing the product behavior. State the level of support or implementation directly.
Prefer roles to names in examples
Section titled “Prefer roles to names in examples”incl-008 should GuidesAPI docsMarketingBlog Use a role, such as the developer or a reviewer, instead of a person’s name when the example works without one. When an example needs names, vary them across examples so that no one region, culture, or gender dominates a document or documentation set.
Examples
- ✓ When a developer shares a report, the reviewer gets a notification.
- ✓ In the examples, Priya shares a report with Diego, and Wei approves it.
- ✗ In the examples, Bob shares a report with Alice, and John approves it.
Rationale
A role names the person by what they do in the example, so it raises no question of pronoun, origin, or stereotype. When names are needed, repeating names associated with one group makes that group look like the default; variation lets more readers see people like themselves in the content.
Avoid stereotypes in examples
Section titled “Avoid stereotypes in examples”incl-009 should GuidesAPI docsMarketingBlog Don’t rely on stereotypes in examples, images, or job-role depictions. Across a documentation set, represent a variety of genders, ethnicities, ages, abilities, and socioeconomic backgrounds.
Examples
- ✓ In the diagram, one engineer deploys the fix while another documents it.
- ✗ In the diagram, the male engineer deploys the fix while his female colleague documents it.
Rationale
A stereotype assigns a role or trait based on identity rather than the example’s purpose. Varying who performs each role avoids reinforcing that assumption.
Avoid US-centric examples
Section titled “Avoid US-centric examples”incl-010 should GuidesAPI docsMarketingBlog Avoid examples that assume a US, Western, or affluent lifestyle. Choose scenarios that don’t require knowledge of specific holidays, sports, foods, or cultural practices.
Examples
- ✓ The sample app tracks scores for a local sports league.
- ✗ The sample app tracks touchdowns for a fantasy football league.
Rationale
A scenario rooted in one region can make the example harder to understand and adapt elsewhere.
Include diverse family structures
Section titled “Include diverse family structures”incl-017 should GuidesAPI docsMarketingBlog Represent different family and household structures across examples and images. Don’t default to a nuclear family of two parents and biological children.
Examples
- ✓ The sample calendar shows a household of four sharing chores.
- ✗ The sample calendar shows a mom, a dad, and their two kids sharing chores.
Rationale
Examples that always show one family structure treat it as the norm. Varying households avoids that assumption.
Don’t generalize about groups
Section titled “Don’t generalize about groups”incl-018 should GuidesAPI docsMarketingBlog Don’t make generalizations about people, countries, regions, or cultures, including positive or neutral generalizations.
Examples
- ✓ Some developers prefer minimal interfaces.
- ✗ Japanese developers prefer minimal interfaces.
Rationale
A group label does not establish that every member shares a trait or preference. Limit the statement to the people or evidence it actually describes.
Don’t disparage any group
Section titled “Don’t disparage any group”incl-024 should GuidesAPI docsMarketingBlog Don’t use figures of speech or wording that disparages or insults any group of people.
Examples
- ✓ The configuration requires no coding experience.
- ✗ The configuration is so simple your grandmother could do it.
Rationale
A joke or comparison based on a group turns that group into the target and distracts from the technical point.
Don’t frame readers by language background
Section titled “Don’t frame readers by language background”incl-021 should GuidesAPI docsMarketingBlog Don’t frame content around native speakers and non-native speakers of English. Describe the language need or feature without classifying the reader’s background.
Examples
- ✓ The glossary defines every term in plain language.
- ✗ The glossary is designed for non-native English speakers.
Rationale
A reader’s first language does not determine whether they need a glossary or plain language. Describe the content feature and the need it meets.