Writing inclusive documentation Edit

Note: Highlight: Write documentation using inclusive language, word choice, and examples.

The WordPress community is welcoming and inclusive. Write WordPress documentation considering inclusivity of people of all demographics.

Unbiased documentation Unbiased documentation

Write documentation that is unbiased towards the reader and any kind of person in general. While documenting particularly demanding/sensitive topics, take the time to educate yourself thoroughly. Ensure that your document doesn’t have content that may hurt or offend someone unintentionally.

While writing unbiased documentation:

  • Be inclusive of gender identity, race, culture, ability, age, sexual orientation, and socioeconomic class. Include a wide variety of professions, educational settings, locales, and economic settings in examples.
  • Avoid politicized content. In case political content is to be included, remain neutral.
  • Follow accessibility guidelines.
  • Avoid content that would insult or cause harm to people.
  • Don’t make any generalizations about people, countries, and cultures, not even positive or neutral generalizations.
  • Don’t write prejudiced and discriminatory content against minority communities.
  • Avoid terms related to historical events.

Top ↑

Replacing established terms Replacing established terms

Various words that are deemed to be non-inclusive are often used in documentation. If replacing those terms causes confusion for readers, you can refer to the non-inclusive term in parentheses in the first use, and subsequently use the inclusive term throughout the rest of the document.

Examples

Tip: Recommended: If disallowed_keys (sometimes called as blacklist_keys) exists in the database, the stored value will be returned.


Tip: Recommended: If disallowed_keys (previously known as blacklist_keys) exists in the database, the stored value will be returned.


Tip: Recommended: The comment blocklist (sometimes called a blacklist) shows blocked and spam comments. Comments that are not on the blocklist are published.

Recommended Not Recommended
deny list, blocklist, disallowed, unapproved blacklist
allowlist, allowed, approved whitelist
main master
primary/subordinate master/slave
site admin, website author, web developer webmaster
built-in, core native

Top ↑

Avoid ableist and profane language Avoid ableist and profane language

Be thoughtful of word choice – particularly slang and ableist language. Don’t use slang, violent and derogatory language such as dumbass and bitch.

Examples

Warning: Not recommended: GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ is damn useful stuff.


Tip: Recommended: GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ is a versatile editor.


Warning: Not recommended: Only morons use this APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways..


Tip: Recommended: Using this APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is not advised.

Top ↑

Writing about genders Writing about genders

Use gender-neutral language, including pronouns. When writing about a real individual, use their preferred pronouns. Avoid gendered language such as manpower, man-hours, chairman, etc. For more information, see Pronouns and genders and they, their, them.

Examples

Recommended Not Recommended
human-power, staff, personnel, workforce manpower
humankind, humanity, people man, mankind
operates, controls, utilizes mans
manufactured manmade
chairperson chairman
everyone, folks, people guys, gals, girls, boys

Don’t use he, him, his, she, her, or hers while refencing people. To write around pronouns, you can:

  • Rewrite using the second person (you).
  • Rewrite the sentence to have a plural noun and pronoun.
  • Use the words person or individual.
  • Use articles the, an, or a instead of a pronoun.
  • Use a plural pronoun such as they, their, or them, even if it references a single individual.

When writing about a person, use the pronouns that the person prefers. Only use gendered pronouns such as he, him, his, she, her, or hers, or other pronouns if a particular individual prefers to be identified with them. It’s acceptable to use gendered pronouns in direct quotations of people who prefer being identified with those pronouns.

Top ↑

Using diverse examples Using diverse examples

Represent diverse perspectives and scenarios in text and media. Make use of inclusive and a diverse range of names, ages, gender identities, locations, professions, and cultures while depicting people.

  • Avoid making generalizations about people, religions, cultures, regions, and countries.
  • Avoid unintentional racial and cultural bias while writing examples.

Top ↑

Accessibility and disability Accessibility and disability

  • Research the terminology that the people with disability want to be identified with.
  • Don’t refer to people without disabilities as normal, fit or healthy; terms that would demean people with disabilities. This includes terms that are judgmental and victimize people with disabilities as abnormal or sick.

Top ↑

Accessibility terminology Accessibility terminology

Recommended Not Recommended
person with disability the disabled, handicapped, differently abled, challenged, abnormal
person without disability normal person, healthy person, able-bodied
has [disability] victim of, suffering from, affected by, stricken with
unable to speak, uses synthetic speech dumb, mute
deaf, low-hearing hearing-impaired
blind, low-vision vision-impaired, visually-challenged
cognitive or developmental disabilities mentally-challenged, slow-learner
person with limited mobility, person with a physical disability crippled, handicapped

For more information, see Accessibility.

Last updated: