Project: Pixie (Observability and Analysis / Observability)
File: inclusive_naming_guide.md

We write our code, documentation, review comments, and other assets 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. These are only suggestions. The author, reviewers, and project maintainers will make the final call. 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. Choose alternative words depending on the context. Things to avoid: Phrases referring to mental health: sanity / crazy / insane Words related to physical or mental disabilities: blind / cripple / dummy How to fix ableist language: Try replacing the word with a phrase that has no underlying negative connotations. Example: crazy outliers baffling outliers, dummy variable placeholder variable. Some points in our code, documentation and comments contain needless assumptions about the gender of a future reader, user, etc. Example: When the user logs into his profile. Things to avoid: Gendered pronouns: he / she / him / her / his / hers, etc. Instances of the phrases he or she, his/hers, (s)he, etc. All of these still exclude those who don't identify with either gender, and implicitly (slightly) favor one gender via listing it first. Guys as a gender-neutral term, which has male associations. Usually in comments it implies anthropomorphism of inanimate objects and should be replaced with a more precise technical term. If it does refer to people, consider using everyone, folks, people, peeps, y'all, etc. Other gendered words: brother, mother, man, etc. Cases that are likely fine to leave alone include: References to a specific person (Rachel is on leave; update this when she is back.). A name (Guy and He are both valid names). A language code (he is the ISO 639-1 language code for Hebrew). He as an abbreviation for helium. The Spanish word he. References to a specific fictional person (Alice, Bob, ...). For new code/comments, consider using just A, B as names. Quotations and content of things like public-domain books. Partner agreements and legal documents we can no longer edit. Occurrences in randomly generated strings or base-64 encodings. Content in a language other than English unless you are fluent in that language. How to fix gendered language: Try rewording things to not involve a pronoun at all. In many cases this makes the documentation clearer. Example: I tell him when I am all done. I tell the owner when I am all done. This saves the reader a tiny bit of mental pointer-dereferencing. Try using singular they. Try making hypothetical people plural. When the user is done he'll probably... When users complete this step, they probably.... When referring to a non-person, it or one may be good alternatives (wikipedia link). Some phrases have underlying racial connotations, or reinforce the notion that some races are better than others. Things to avoid: Terms that reinforce the notion that one race is good or bad: blacklist, whitelist Words rooted in historical events regarding race: slave, master How to fix racist language: Replace the term with an alternative that does not change its meaning. Example: whitelist allowlist, master main. <https://developers.google.com/style/inclusive-documentation> <https://chromium.googlesource.com/chromium/src/+/master/styleguide/inclusive_code.md>