# Accessibility, inclusive language, and global audience detail

Detail for: accessibility, inclusive documentation, writing for translation and
a global audience. Source: developers.google.com/style (Accessibility,
Inclusive documentation, Writing for a global audience).

## Accessible documentation

~15% of the world's population has an accessibility need; accessible writing
improves the experience for everyone. Key rules:

- **Semantic structure**: use real headings (h1/h2/h3) in order; keep a logical
  reading order; use proper list, table (caption, th, scope), and link markup.
- **Links**: descriptive link text (see formatting.md) — screen reader users
  often tab between links alone.
- **Images and multimedia**: alt text for all informative images, `alt=""` for
  decorative ones; provide transcripts or descriptions for videos; captions for
  audio/video; don't use images for text.
- **Keyboard access**: all interactive elements reachable and operable by
  keyboard.
- **Don't rely on visual-only cues**: no "the button on the left", no color as
  the only differentiator, no "above/below/right-hand side" directions.
- **Tables**: real table markup, not layout tables; empty cells use ` `
  or mention "N/A".
- **Language**: simple, plain sentences; avoid unusual fonts, all-caps text
  (screen readers may spell it out), and abbreviations that aren't defined.
- **Contrast and zoom**: text must be readable with enlarged fonts; don't
  hard-wrap text.
- Requirements and normative guidance live in WCAG 2.x — cite those when
  specific compliance is needed.

## Inclusive documentation

Avoid bias and harm; plain, precise language is more inclusive.

- **Gender**: avoid unnecessarily gendered language. Use singular *they*;
  don't address readers as "guys" or use *he/she*. When referring to a person
  whose gender is unknown or irrelevant, use *they*.
- **Ableist language**: avoid metaphors and idioms that marginalize — words to
  steer clear of include *crazy, insane, dumb, blind spot, cripple, tone
  deaf, sanity check, grandfathered, blacklist/whitelist, master/slave,
  manhours, guys* and similar. The word list flags many of these.
- **Non-inclusive terms in code**: if a term appears as a code keyword or
  established industry term, either note the guidance in documentation or write
  around it, per the word list's "don't use" markers. Don't casually keep
  offensive terms just because they're in code.
- **Examples**: use diverse names, genders, ages, and locations; gender-neutral
  pronouns; avoid stereotypes (defaulting to one gender for a role, or Western
  names for everyone).
- **Accessibility as a topic**: discuss disability and accessibility in a
  respectful, non-heroic way; use person-first or identity-first language as
  the community you're writing for prefers (the guide recommends avoiding bias
  and harm, and educating yourself on preferred terminology).
- **People-first**, e.g., "users with reduced vision" rather than labels that
  define people by a condition, where appropriate.
- Avoid figurative/idiomatic language that can be misinterpreted or distract.

## Global audience / translation

The reader may be reading translated or non-native English. Write so meaning
survives translation:

- Short, unambiguous sentences; active voice; direct address ("you"); standard
  English word order (subject-verb-object).
- Consistency: use the same word for the same concept throughout; don't
  synonym-swap for variety — translation memories rely on consistency.
- Define abbreviations on first use; avoid culturally specific references,
  idioms, humor, puns, sports metaphors, and references to local customs.
- Avoid seasonal and "current events" references (timeless docs, see
  strategy.md).
- Dates/times and units: use the unambiguous formats in technical.md.
- Examples: use the reserved example domains and fictitious data in
  formatting.md; avoid real PII from any culture.
- Don't rely on wordplay or double meanings.
- Keep formatting simple: translation systems may mangle complex markup.

## Practical rules that most often matter

1. Descriptive link text; never "click here".
2. Alt text for every informative image.
3. No directional or color-only instructions.
4. Short sentences, plain words, consistent terminology.
5. Spell out abbreviations on first use.
6. Singular *they*; no gender stereotypes in examples.
7. Run the word list check on any term with inclusive-language flags.