awesome-copilot/instructions/inclusive-language-bias-awareness.instructions.md

description	applyTo
Comprehensive guidelines for using inclusive, bias-aware language in code, documentation, and all technical artifacts	**

Inclusive Language and Bias Awareness

Purpose

This instruction file provides guidance for creating inclusive, respectful, and bias-aware technical content across all aspects of software development, including code, documentation, comments, variable names, commit messages, and user-facing text.

Core Principles

1. Inclusive by Default

Use language that welcomes everyone:

• Choose terms that are inclusive and respectful of all people
• Avoid language that excludes, stereotypes, or marginalizes groups
• Consider diverse backgrounds, cultures, and experiences
• Default to neutral and professional language

Think globally:

• Remember that code is read by people worldwide
• Avoid idioms or cultural references that may not translate
• Use clear, straightforward language
• Consider non-native English speakers

2. People-First Language

Put people before labels:

• Use "person with disability" not "disabled person"
• Use "developer who uses a screen reader" not "blind developer"
• Emphasize the person, not the characteristic
• Avoid defining people by a single attribute

Respect identity:

• Use gender-neutral language by default
• Avoid unnecessary gender references
• Respect self-identified terms and pronouns
• Don't make assumptions about users or developers

3. Technical Terminology Review

Audit and update problematic terminology:

Problematic master/slave terminology:

- master/slave
+ primary/replica
+ leader/follower
+ main/worker
+ primary/secondary

Problematic whitelist/blacklist terminology:

- whitelist/blacklist
+ allowlist/denylist
+ permitted/blocked
+ approved/rejected

Problematic grandfather/legacy terminology:

- grandfathered in
+ legacy exception
+ pre-existing
+ historically included

Other terms to reconsider:

- sanity check
+ verification check
+ validation check
+ confidence check

- dummy value
+ placeholder value
+ sample value
+ test value

- master branch
+ main branch

- native/non-native
+ built-in/third-party
+ core/external

Naming Conventions

Variable and Function Names

Use descriptive, neutral names:

Good examples:

// Descriptive, neutral names
const primaryDatabase = config.database.primary;
const replicaDatabase = config.database.replica;
const userPermissions = getUserPermissions();
const isAuthorized = checkAuthorization(user);
const mainController = new Controller();

Avoid examples:

// Problematic names
const masterDB = config.database.master; // Use 'primary' or 'main'
const slaveDB = config.database.slave; // Use 'replica' or 'secondary'
const whitelist = getWhitelist(); // Use 'allowlist'
const sanityCheck = performSanity(); // Use 'validation'

Gender-neutral examples:

// Good: Gender-neutral
const user = getUser();
const developer = getDeveloper();
const administrator = getAdmin();
const participant = getParticipant();

// Avoid: Gendered
const guys = getUsers(); // Use 'users', 'people', 'folks', 'team'
const chairman = getChair(); // Use 'chairperson', 'chair', 'lead'
const manpower = getResources(); // Use 'staff', 'workforce', 'team size'

Class and Type Names

Use inclusive, professional names:

// Good: Professional, inclusive naming
interface UserProfile {
  id: string;
  displayName: string;
  preferredPronouns?: string;
  emailAddress: string;
}

class AccessControlManager {
  checkPermissions(user: User, resource: Resource): boolean;
  grantAccess(user: User, resource: Resource): void;
  revokeAccess(user: User, resource: Resource): void;
}

type AuthorizationLevel = "read" | "write" | "admin";

Database and Schema Names

Apply inclusive naming to database objects:

-- Good: Inclusive naming
CREATE TABLE primary_users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255),
  created_at TIMESTAMP
);

CREATE TABLE replica_sync_status (
  id SERIAL PRIMARY KEY,
  last_sync TIMESTAMP
);

-- Avoid: Problematic naming
-- CREATE TABLE master_users ...
-- CREATE TABLE slave_sync_status ...

Code Comments and Documentation

Writing Inclusive Comments

Be professional and neutral:

Good examples:

/**
 * Validates user input before processing.
 * Checks for common security issues and malformed data.
 *
 * @param input - The user-provided data to validate
 * @returns true if validation passes, false otherwise
 */
function validateInput(input: string): boolean {
  // Implementation
}

/**
 * Synchronizes data from the primary database to replica databases.
 * Ensures data consistency across all database instances.
 */
async function syncDatabases(): Promise<void> {
  // Implementation
}

Avoid examples:

// Avoid: Ableist language
// This is a sanity check to make sure the user isn't crazy
// Prefer: This validates the user input is reasonable

// Avoid: Violent language
// Kill the process if it's taking too long
// Prefer: Terminate the process if it exceeds timeout

// Avoid: Gendered assumptions
// When the user clicks, he will see...
// Prefer: When the user clicks, they will see...

Documentation Best Practices

Use inclusive examples:

## User Profile Example

A user might have the following profile information:

{
"name": "Alex Chen",
"email": "alex@example.com",
"role": "developer",
"pronouns": "they/them"
}

Note: Users can specify their preferred pronouns in their profile settings.

Avoid gendered examples:

<!-- Avoid -->

For example, if a developer wants to test the API, he can use:

<!-- Prefer -->

For example, if a developer wants to test the API, they can use:

Use diverse names in examples:

<!-- Good: Diverse, international names -->

- Alex Chen (Software Engineer)
- Priya Patel (Product Manager)
- Jordan Williams (Designer)
- Amara Okafor (Data Analyst)

<!-- Avoid: Only Western, traditionally male names -->

- John Smith
- Bob Johnson
- Mike Davis

User-Facing Text

UI Text and Messages

Be welcoming and neutral:

Good examples:

const messages = {
  welcome: "Welcome! Let's get started.",
  emptyState: "No items yet. Create your first one to get started.",
  error: "We encountered an issue. Please try again.",
  success: "Your changes have been saved.",
  loading: "Loading your data...",
};

Avoid examples:

// Avoid gendered language
"Welcome, guys!"; // Use "Welcome, everyone!" or "Welcome!"

// Avoid ableist language
"Click here"; // Use "Select this option" (screen reader friendly)

// Avoid violent language
"Kill the session"; // Use "End the session"

// Avoid cultural assumptions
"Starting on Monday"; // Specify "Starting on the first day of the week"

Error Messages

Be helpful and respectful:

Good examples:

// Clear, helpful, respectful
"The email address format is not recognized. Please check and try again.";

"Access to this resource requires authentication. Please sign in.";

"The operation could not be completed. Please verify your input and try again.";

Avoid examples:

// Avoid blaming language
"You entered an invalid email."; // Prefer: "The email format is not recognized."

// Avoid patronizing language
"Oops! Silly you!"; // Prefer: "Please check your input."

// Avoid technical jargon for users
"FATAL: Segmentation fault"; // Prefer: "An error occurred. Please try again."

Bias Awareness in AI-Generated Code

Review AI Suggestions for Bias

When using AI tools like Copilot, watch for:

Gendered assumptions:

// AI might suggest:
const user = { name: "John", gender: "male" };

// Consider instead:
const user = {
  name: "Jordan",
  // Only include gender if functionally required
  // If required, make it optional and inclusive
  gender?: "male" | "female" | "non-binary" | "prefer-not-to-say"
};

Stereotypical examples:

// AI might suggest:
const doctor = { name: "Dr. Smith", gender: "male" };
const nurse = { name: "Emily", gender: "female" };

// Consider instead:
const doctor = { name: "Dr. Patel", specialty: "cardiology" };
const nurse = { name: "Jordan", certification: "RN" };

Cultural assumptions:

// AI might suggest:
const holidays = ["Christmas", "New Year's"];

// Consider instead:
const holidays = [
  "New Year's Day",
  "MLK Day",
  "Presidents Day",
  // Include diverse cultural and religious holidays
];

Challenge Biased Patterns

Question AI suggestions that:

• Make assumptions about gender, race, ethnicity, or ability
• Use stereotypical examples or scenarios
• Exclude or marginalize certain groups
• Reflect historical biases in training data

Take action:

• Modify AI suggestions to be more inclusive
• Request alternative suggestions
• Document problematic patterns
• Share concerns with your team
• Report issues to tool maintainers

Testing and Validation

Inclusive Test Data

Use diverse, realistic test data:

Good examples:

const testUsers = [
  { name: "Alex Chen", email: "alex@example.com", locale: "en-US" },
  { name: "Priya Patel", email: "priya@example.com", locale: "en-IN" },
  { name: "Yuki Tanaka", email: "yuki@example.jp", locale: "ja-JP" },
  { name: "Amara Okafor", email: "amara@example.ng", locale: "en-NG" },
  { name: "Jordan Williams", email: "jordan@example.com", locale: "en-GB" },
];

Test edge cases:

// Test different name formats
const nameTestCases = [
  "Jordan", // Single name
  "Alex Chen", // Two names
  "María José García", // Names with accents
  "Björk Guðmundsdóttir", // Nordic names
  "Sun-Hee Park", // Hyphenated names
  "O'Brien", // Names with apostrophes
  "van der Berg", // Names with prefixes
];

Accessibility in Testing

Include accessibility tests:

describe("Form accessibility", () => {
  it("should have proper labels for all form fields", () => {
    // Test that all inputs have associated labels
  });

  it("should be keyboard navigable", () => {
    // Test keyboard navigation
  });

  it("should have proper ARIA attributes", () => {
    // Test ARIA labels and roles
  });
});

Commit Messages and PR Descriptions

Inclusive Communication

Good examples:

feat: Replace master/slave terminology with primary/replica

Updated database configuration to use more inclusive terminology.

- Renamed master_db to primary_db
- Renamed slave_db to replica_db
- Updated documentation to reflect changes

Breaking change: Configuration files need to be updated

docs: Add examples with diverse user names

Updated documentation examples to include diverse, international names
that better represent our global user base.

Avoid:

// Avoid gendered language
"Fixed the issue with user profiles - they were driving me crazy"

// Prefer
"Fixed validation issue in user profiles"

Localization and Internationalization

Global Perspective

Consider internationalization:

// Good: Locale-aware formatting
const formatter = new Intl.DateTimeFormat(userLocale);
const formattedDate = formatter.format(date);

// Good: Support for multiple languages
const messages = {
  "en-US": { greeting: "Hello" },
  "es-ES": { greeting: "Hola" },
  "ja-JP": { greeting: "こんにちは" },
  "ar-SA": { greeting: "مرحبا" },
};

Avoid cultural assumptions:

// Avoid: Assumes Western date format
"Enter date as MM/DD/YYYY";

// Prefer: Locale-aware
"Enter date in your local format";
// Or use a date picker that handles localization

Continuous Improvement

Regular Audits

Conduct periodic reviews:

• Audit codebase for non-inclusive language
• Review documentation for bias and assumptions
• Check UI text for welcoming tone
• Evaluate test data for diversity
• Update terminology based on evolving best practices

Team Education

Foster inclusive culture:

• Provide training on inclusive language
• Share resources and best practices
• Encourage open discussions
• Create safe space for questions
• Learn from mistakes and improve

Feedback Mechanisms

Welcome input:

• Encourage team members to point out non-inclusive language
• Create clear processes for suggesting improvements
• Act on feedback promptly
• Thank people for raising concerns
• Document changes and learnings

Resources

Terminology Guides

• Microsoft Style Guide - Bias-free communication
• Google Developer Documentation Style Guide - Inclusive documentation
• Salesforce Inclusive Language Guidelines
• The Conscious Style Guide

Industry Initiatives

• Inclusive Naming Initiative
• Linux Foundation: Inclusive Naming
• IETF Terminology Working Group

Summary Checklist

Before committing code, ask yourself:

• Have I used inclusive, neutral terminology?
• Are variable and function names free from bias?
• Do code comments use respectful language?
• Does documentation include diverse examples?
• Are user-facing messages welcoming to all?
• Have I avoided gendered language?
• Are test cases representative of diverse users?
• Did I review AI suggestions for bias?
• Would this code be welcoming to any developer?
• Am I proud to have my name associated with this language?

Conclusion

Inclusive language is not about being "politically correct" - it's about being professional, respectful, and welcoming to all people who use or contribute to our software. By consciously choosing inclusive language, we:

• Create better products that serve diverse users
• Build stronger teams where everyone feels welcome
• Write clearer code with precise, professional terminology
• Lead by example in the software development community
• Future-proof our codebases with modern, inclusive practices

Remember: Words matter. Choose inclusively.