1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
|
# 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.
|
