Version 1.0 | April 2021
UCI is committed to equity, diversity, and inclusion. Language used by the Office of Information Technology (OIT) must reflect these values.
Scope
This document is an Architecture Review Board (ARB) Standard to be followed by all OIT staff. OIT encourages everyone at UCI to be mindful of these issues and participate in making these decisions with respect and a broad viewpoint.
This document should guide your terminology choices in your documentation, codebase, and discussions. Where you control the choice of words, you should choose wisely. We encourage you to use terminology from this guide in areas you can but understand there may be times when words from outside systems, legacy technology, or existing standards constrain your options. In those cases, consider inclusive alternatives, such as providing a mapping from old to new terminology, with source attribution when necessary.
Principles
Favor gender-neutral terms whenever possible. Avoid constructions like “he or she”, “he/she” and “s/he”; singular “they” has been in use for centuries.
| Use this | Not this |
|---|---|
| they, them | he, she |
| their | his, her |
| folks, team, y’all | guys, gals |
| chair, moderator, chairperson | chairman |
| humanity, people, humankind | man, mankind |
| other UC campus | sister school, sister campus |
| legacy status, preexisting | grandfathered |
| counterpart, indispensable | right-hand man |
| person hours or engineer hours or level of effort (hours) | man hours, manpower |
| attacker-in-the-middle | man-in-the-middle |
When writing about a specific, real-world person, use the pronouns that person prefers. If possible, ask them which pronouns to use. Consider adding your preferred pronouns to your email signature or screen name to make this task easier on others.
Use inclusive names in examples. For people, pick names with origins in multiple cultures.
Don’t make generalizations about people, countries, regions, and cultures. Even if your intent is to cast them in a positive light.
Be mindful of the layers of meaning behind your word choices. The history of a term matters, but connotations gained since the coining of a term matter, too.
| Use this | Not this |
|---|---|
| allowlist, safelist | whitelist |
| denylist, blocklist | blacklist |
| glass box testing, clear box testing | white box |
| functional testing, acceptance testing | black box |
| built-in feature | native feature |
| core concept, top-level | first-class citizen |
| maintenance, upkeep | housekeeping tasks |
Favor direct descriptions of the actions taken and roles played. Avoid metaphors, which can introduce unneeded baggage. Prefer verbs to nouns.
| Use this | Not this |
|---|---|
| primary/replica, primary/standby, primary/secondary | master/slave |
| main branch | master branch |
| against the grain, counterproductive | off the reservation |
Focus on people and not disabilities or circumstances. Prefer “people-first language,” such as “people with disabilities” or “people experiencing homelessness.” Research the community you’re discussing, as there are exceptions: some individuals in the blind, deaf, and autistic communities prefer disability-first language. When referencing users with disabilities, avoid the use of “impairment”. The term Deaf with a capital D refers to people who identify as culturally Deaf– sharing a common culture and a signed language– while deaf with a lowercase d refers to a person who has the condition of hearing loss who does not necessarily identify with the culture.
| Use this | Not this |
|---|---|
| screen reader/magnifier user | user with a visual impairment |
| D/deaf or hard of hearing | hearing impaired |
Avoid ableist language. It is easy to fall back on problematic idioms, especially when trying to be conversational. These terms can go unnoticed; make an effort to notice them.
| Use this | Not this |
|---|---|
| smoke test, quick check, confidence check, coherence check | sanity check |
| placeholder value or sample value | dummy value |
| hinder | cripple |
| ignore | blind to, deaf to |
| inconsiderate, thoughtless, careless | tone deaf |
Avoid slang and idioms that can confuse or detract from your message. Do not rely on implicit contextual understandings that may not be shared by your audience, as they may be separated by time, distance, and culture.
Avoid violent language, as it will distract from your meaning.
| Use this | Not this |
|---|---|
| perimeter network | demilitarized zone (DMZ) |
| stop responding | hang |
| halt, stop | kill (a process) |
| feed two birds with one scone | kill two birds with one stone |
| delete | nuke |
Don’t use derogatory terms. There is no need.
Timeline
Wherever possible, start using better terms immediately. Set aside time in your schedule to make the changes where effort is required. Be forgiving to others as we all work to break old habits and form new ones.
If changes are to be postponed, work with your supervisors to set a reasonable deadline for making the change. Consider setting up a system with aliases or subclasses that allow new code to use better terminology. Add comments or other documentation to explain that you are aware the term is outmoded and that changes will be made when possible. For example:
/*
TODO The terminology used in this file will be replaced with “Primary” and “Secondary” within the year. The wording here reflects the underlying ISO standard.
*/If your internal naming convention has to convert to an external naming convention that would run afoul of this standard, include a comment to note the limitation. For example:
/*
This terminology is part of the underlying ISO standard; we cannot update it at this time.
*/References
This guide is heavily indebted to the following material found online, and compiles many of the same ideas and contextualizes them for our purposes.
- Microsoft’s “Bias Free Communication” documentation
- Google’s inclusive documentation guide and translation guide
- Apple’s ongoing “Updates to Coding Terminology” project
In addition, many of our counterparts in the technology community are making similar changes: