Type: Guideline
Version 2025
Goal
We want to bring everyone into the conversation and foster inclusive excellence. Language in this guide reflects Office of Information Technology (OIT) values and University of California core values.
Scope
This document is an Architecture Review Board (ARB) Guideline for OIT staff. OIT encourages everyone at UCI to consider these issues and participate in making language choices with respect and a broad viewpoint.
This document advises on inclusive terminology for use in documentation, codebases, discussions, and more. Where you control the choice of words, you have an opportunity to choose wisely. We encourage you to use terminology from this guide in areas you can, and 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.
How to use this guide
This guide showcases the way that language matters, and that seemingly inconsequential terminology choices can actually have large effects.
To best use this guide, get your team together to review the language you use, and decide if anything should change.
It is best to acknowledge up front that these discussions can be fraught. Show patience for those following in your footsteps, as well as patience for those who might expect you to follow faster. Try to bring others along with you on this journey, but do not expect everyone to move with the same alacrity. Be generous when others disagree generously; extend grace and strive toward mutual understanding. Be understanding when people make mistakes and fall into old habits; we are all works in progress.
Team discussions
This document empowers your team to discuss their terminology and make conscious decisions about what words they use. Your context will matter greatly as you do so: your choices will be affected by the business processes you are closest to, the development language you use, the cultural references of those present, and a host of other factors. This guide highlights a few considerations you may not otherwise be aware of, injecting a few more ideas into that conversation.
We encourage you to write a glossary of terms used. Include acronyms, technical jargon, and business units. Try to make something that would be useful to a new hire on your team who has none of the experience you’ve acquired. Listen closely to new members on your team, who will have the least familiarity with the localized meanings that more established employees may have internalized. Try to uncover misunderstandings: places where terms overlap, where one word means different things in different contexts, or where one thing has different names. Schedule a reminder to keep the glossary updated.
If you uncover terminology that needs updating, you should make those changes. Clarify meanings; reduce duplication; be more consistent. We recognize that in some cases doing so is not possible, and in other cases terminology changes can cause enough confusion that it’s not the right choice. But make those choices proactively, not by inertia.
Where to look for terminology
Every team will develop their own names for things, if only to speed up conversations. Here’s an incomplete list of places where those terms might be hiding:
- Codebases
- Acronyms
- Documentation
- Names of servers, repositories, teams, positions, directories
- Job postings and descriptions
- Account names in the campus directory, SaaS services, etc
- Tags and labels
- Meeting names
- Business groups on campus that your team interacts with
- Cloud services like Azure and Amazon Web Services
- Tools your team uses for project tracking, development, continuous integration, testing, etc
- Project code names
Principles & Terminology
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 |
| upset, unhappy | hysterical, hysterics |
| responsibilities | ball and chain |
| prime example, wunderkind | golden boy |
When writing about a specific, real world person, use the pronouns that person uses. 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 possible layers of meaning behind your word choices. The history of a term matters, and the connotations gained since the coining of a term matter.
| 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 |
| arrogant | uppity |
| early career | junior employee, low man on the totem pole |
| meeting, conference, symposium | pow-wow |
| guideline | rule of thumb |
Favor direct descriptions of the actions taken and roles played. Be careful with metaphors, which can imply meanings you don’t intend. Prefer verbs to nouns.
| Use this | Not this |
|---|---|
| primary/replica, primary/standby, primary/secondary, lead/follower | master/slave |
| main branch | master branch |
| against the grain, counterproductive | off the reservation |
Focus on people and not disabilities or circumstances. Default to “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 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 a hearing loss who does not necessarily identify with the culture.
| Use this | Not this |
|---|---|
| screen reader/magnifier user | blind, user with a visual impairment |
| D/deaf or hard of hearing | hearing impaired |
Avoid ableist language that use disability terms to impart negative connotations. It is easy to fall back on problematic idioms, especially when trying to be conversational. These terms can go unnoticed; make the 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 |
| cognitive disabilities, developmental disabilities | mentally handicapped, differently abled, slow learner |
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, cancel | kill (a process) |
| feed two birds with one scone delete | kill two birds with one stone nuke |
| retrospective, after action report | post-mortem |
| operator presence control, vigilance control | dead man’s switch |
Don’t use derogatory terms. There is no need.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119
Requirements
Discussion
- Teams SHOULD meet and talk about the language they use, and review their terminology in light of the ever-changing cultural context.
- Teams MAY request an outside facilitator for this discussion
- Teams SHOULD identify language that falls short of the principals in this guide, and work as a group to determine how best to deal with each term
- Teams SHOULD be mindful of the power dynamics when having these discussions. Managers and leads can have oversized influence, and should be careful to listen and respect the wider team.
- Teams SHOULD meet for this purpose at least yearly
- Teams SHOULD maintain a glossary of terminology used by their team, to facilitate onboarding
Adoption
- Teams SHOULD adopt more inclusive language whenever possible. Look for opportunities in your:
- Codebases
- Documentation
- Outreach & Communication
- Job descriptions
- Interview questions
- When adopting inclusive language is not possible, teams SHOULD document the barriers to adoption
- Teams SHOULD discuss those barriers with other parties if doing so could help remove the barrier
Ownership
Direct questions about this document to the Owner: Seth A. Roby sroby@uci.edu
Timeline & Enforcement
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 the 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 match 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; internal uses should favor "primary" and "secondary".
*/
License
This work is published under version 4 of the Creative Commons Attributions Non-commercial (CC-BY-NC) licence.
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
- The National Institute for Standards and Technology (NIST)’s Guidance for NIST Staff on Using Inclusive Language in Documentary Standards
- The American Psychological Association (APA)’s Bias-Free Language
In addition, many of our counterparts in technology and government are making similar changes:
- Plain Language
- Chrome is moving toward “block list” and “allow list”
- GitHub abandons the term “master”
- Linux kernel upcoming changes
- IETF is drafting standards to change their language
- Twitter updated lots of terms internally
- Python is discussing these changes
- Drupal is following along
- Django is too
- Renaming the Scrum Master role