The WordPress community is welcoming and inclusive. Write WordPress documentation considering inclusivity of people of all demographics.
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.
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
disallowed_keys
(sometimes called as blacklist_keys
) exists in the database, the stored value will be returned.
disallowed_keys
(previously known as blacklist_keys
) exists in the database, the stored value will be returned.
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 |
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
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 referencing 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.
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.
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.
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.