Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
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.
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.
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.
Be thoughtful of word choice – particularly slang and ableist language. Don’t use slang, violent and derogatory language such as dumbass and bitch.
Warning:Not recommended:GutenbergGutenbergThe 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:GutenbergGutenbergThe 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 APIAPIAn 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 APIAPIAn 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.
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.
human-power, staff, personnel, workforce
humankind, humanity, people
operates, controls, utilizes
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.
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.
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.