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
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
# Numbers, units, and technical terminology detail
Detail for: numbers, dates and times, units of measure, phone numbers,
mathematical notation, abbreviations, product names, trademarks, jargon,
excessive claims. Source: developers.google.com/style (Numbers, Dates and
times, Units of measurement, Phone numbers, Mathematical notation,
Abbreviations, Product names, Trademarks, Jargon, Excessive claims).
## Numbers
- Spell out zero through nine; use numerals for 10 and above.
- "four options", "nine developers", "15 directories".
- Always spell out a number that starts a sentence (or rewrite so it doesn't):
- "Fifteen directories are created." / "In general, avoid sending files
larger than 164 MB as attachments."
- Exception: it's OK, though non-optimal, to start a sentence with a four-digit
year.
- Ordinals are always words: first, fifth, twelfth — never 1st, 5th, 43rd.
- Use numerals for dimensions, percentages, currency, measurements, and
technical quantities ("a 128-bit system", "10%", "$5", "version 12").
- Fractions: prefer decimals.
- Ranges of numbers: "15 to 20" (or hyphen in time ranges: "5-10 minutes ago").
- A number followed by a numeral is spelled out: "fifteen 100,000-byte files".
- Use a nonbreaking space between a number and its unit (see below).
## Dates and times
- Dates: full month name, day, four-digit year — "January 19, 2017". Spell out
months and weekdays in full; no "Jan. 19, '17".
- Numeric-only dates: ISO 8601 (YYYY-MM-DD), e.g. 2017-04-15.
- Times: 12-hour clock; "3 PM", "3:45 PM" (capital AM/PM, space before);
omit minutes for round hours; noon and midnight are fine.
- If a product/UI uses 24-hour time, match it throughout the page.
- Time zones: avoid unless necessary. If needed, spell out the region with UTC
offset: "US and Canadian Pacific Standard Time (UTC-8)". Don't abbreviate
time zone names.
- Seasons: avoid ("Q1 2024", not "in winter 2024").
## Units of measure
- Nonbreaking space between number and unit: 64 GB, 25 mm. (Currency, percent,
and angle degrees are exceptions that don't need the space.)
- Temperature: "50° C", "300 K" (space before C/F/K).
- Ranges: repeat the unit and use "to": "-40° C to 85° C", not "-40-85° C".
- Bytes: decimal (kB, MB, GB) vs binary (KiB, MiB, GiB) — use the correct
system for the technology you're documenting.
- Spell out units in prose when the abbreviation isn't clear ("miles per
hour", not "mph" on first use) — check the Abbreviations page.
## Phone numbers
- Example numbers only from the reserved range 800-555-0100 through
800-555-0199 (US). Never real phone numbers.
- Format so the number stays on one line: nonbreaking hyphen (`‑`) and
nonbreaking spaces.
- Include country/area codes when appropriate; extensions: "extension 1234".
## Mathematical notation
- Use HTML entities for math symbols instead of keyboard glyphs (e.g.
`−`, `×`, `≤`); the plus, equals, and division signs may use
keyboard equivalents.
- If a third-party tool renders the math, follow that tool's formatting.
- Accompany numerical concepts with real-world implications; use diagrams or
charts to aid comprehension.
## Abbreviations
- Abbreviations include acronyms (pronounced as words: NATO), initialisms
(letter-by-letter: CIA, PR), shortened words (Dr., min), and contractions.
- **Define on first use**: spell out the full term, then give the abbreviation
in parentheses — "Google Kubernetes Engine (GKE)". Use the abbreviation alone
afterward. (In headings, define it in the first paragraph after.)
- Only abbreviate when the abbreviation saves the reader effort; avoid
unfamiliar or overly specialized abbreviations and internet slang (tl;dr,
ymmv).
- Omit periods in acronyms and initialisms ("PR", not "P.R."); keep them in
shortened words ("Dr.", "etc.").
- Pluralize abbreviations like regular words: "CDs", "OSes" (add `es` to
those ending in s, sh, ch, x). Don't use abbreviations as verbs.
## Product names
- Follow official capitalization; don't rename or stylize products.
- Google product names in title case unless matching a UI label; features
usually lowercase unless officially capitalized.
- Use the full product name on first mention; avoid abbreviations unless the
abbreviation matches the UI.
- Don't use product or feature names as verbs ("google it", "to chrome") or as
possessives.
- Use "the" before tool/API names ("the `gcloud` tool", "the Compute Engine
API"), not before plain product names ("use BigQuery").
## Trademarks
- Use trademarks only as modifiers of a noun: "a Chromebook notebook computer"
— never as a bare noun, verb, possessive, or plural ("google", "Chromebook's
features", "Chromebooks").
- Never alter or abbreviate trademarked terms.
## Jargon
- Jargon = specialized/figurative group terminology (camel case, swim lane,
break-glass, out-of-the-box, solution, workload). Avoid it for global
audiences.
- If you must use a term because readers search for it, define it on first use
or link to a trusted definition.
- Write around the term when possible; keep definitions short.
## Excessive claims
- Don't claim things a reader can't verify or that the future could invalidate:
- Performance/cost claims not backed by verifiable data.
- Security statements that a single incident could falsify ("our service is
completely secure" → "this feature is designed to prevent X").
- Subjective or disparaging statements about third-party products.
- Avoid superlatives: best, simplest, fastest, never, always. Be careful with
ensure and guarantee — use them only when you can actually back them up.
- Describe intended benefits and design, not guarantees.
|
