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
120
121
122
123
124
125
126
127
|
# Grammar and mechanics detail
Detail for: articles, contractions, pluralization, possessives, prepositions,
pronouns, tense, sentence structure, reference verbs, anthropomorphism, italics.
Source: developers.google.com/style (Articles, Contractions, Pluralization,
Possessives, Prepositions, Pronouns, Tense, Sentence structure, Reference verbs,
Anthropomorphism, Italics for terms).
## Articles (a, an, the)
- Always include articles — never drop them for brevity, including in headings.
- Recommended: Create **a** VM instance — Not: Create VM instance
- Use `a` when the next word starts with a consonant **sound**, regardless of
spelling. For abbreviations whose pronunciation varies, choose the article to
match the common pronunciation (e.g., "an SQL database" if you pronounce it
"ess-queue-ell", "a SQL database" if you say "sequel").
## Contractions
- Use contractions, especially negations: *isn't*, *don't*, *can't*. Readers
can miss the word *not* when scanning.
- Don't invent nonstandard contractions (*guides're*, *browser's* for "browser
is") or three-word contractions (*mightn't've*).
- To emphasize a negation you can use formatting, e.g. "is **_not_**".
## Pluralization
- Make subject and verb agree, especially with long or complex subjects:
- Recommended: "The number of entries listed in the directory **is** accurate."
- Recommended: "The request payload and header information **are** logged."
- In product names, don't pluralize (they're proper nouns): "use Project
IDs" — check the word list for specific entries.
- For plural of code elements, don't inflect the code name; add a noun instead
("multiple `config` files", not "multiple configs").
- Don't use parentheses for optional plurals ("file(s)") — see word list
nuance; in general rewrite instead.
## Possessives
- Singular nouns (including ones ending in s): add `'s` — "each vector's
record".
- Plural nouns ending in s: add only `'`: "the developers' guide".
- Don't form possessives from product, feature, or company names when
describing their function; use the name as a modifier or rephrase with *of*:
- Recommended: "the Cloud Console menu" — Not recommended: "Cloud Console's menu"
- Trademarks: never form a possessive. "Chromebook" → "Chromebook's features"
is wrong.
- Code items: avoid possessives entirely; "the value of the `ADDRESS` constant",
not "`ADDRESS`'s value".
## Prepositions
- Include prepositions that increase clarity, omit unnecessary ones, and don't
clutter sentences.
- Recommended: "the client library documentation **for** the language you're
interacting with"
- Not recommended: "...the language with which you're interacting."
- In cross-references use *about*, not *on*: "For more information about
indexes, see ..."
## Pronouns
- Ensure a pronoun clearly refers to its antecedent; if ambiguous, repeat the
noun.
- Recommended: "If you type text in the field, the text doesn't change."
- Not recommended: "...it doesn't change."
- After a demonstrative (`this`/`these`/`that`), include a noun: "Set this
value to true", not "Set this to true".
- Gender-neutral: use singular *they*; never *he/she*, *(s)he*, or generic *he*.
- Use second person (*you*) for the reader; first person (*I* in FAQs, *we* for
the organization) only in specific contexts.
- `that` for restrictive clauses, `which` (with comma) for nonrestrictive:
"the option that you selected", "the option, which is deprecated, ...".
## Tense
- Present tense for general behavior: "The server sends an acknowledgment",
not "will send".
- Future tense (*will*) only to flag a genuinely future action: "The file will
be archived the next time the backup process runs."
- Don't use future tense for how a feature will work after a future release
(write it as current behavior instead — see `reference/strategy.md`).
- Avoid hypothetical *would*: "If you send an unsubscribe message, the server
removes you from the list" — not "You can send... The server would then...".
## Sentence structure
- Put conditions before instructions, and the most important information first.
- Recommended: "If your app is located in one of the following regions, ..."
- Not recommended: "...if your app is located in one of the following regions." (buried at the end)
- Use "For more information, see [link]." rather than "See [link] for more
information."
- "To delete the entire document, click Delete." rather than "Click Delete if
you want to delete the entire document."
- Keep sentences short, vary the openings.
## Reference verbs (API descriptions)
- In API reference descriptions, the first verb matches the reference style:
says *creates*/*returns* (describes what the method does) vs *create*/*return*
(imperative instruction). Follow the existing style of the reference:
- "tasks.insert: Creates a new task on the specified task list."
- Use a parallel, consistent form throughout a reference.
## Anthropomorphism
- Don't have software or objects do human actions: *see, think, feel, want,
believe, tell, assume*, etc.
- Recommended: "A Delimiter object specifies where to split a string."
- Not recommended: "A Delimiter object tells the splitter where a string
should be broken."
- Recommended: "The PC detects a new device."
- Not recommended: "The PC sees a new device."
- Exception: standard idioms in technical vocabulary are fine when the product
uses them (e.g., "the server returns a 404", "the API expects a JSON body").
## Italics for terms (words as words)
- **New terms**: italicize on first mention when defining immediately. Don't
use bold or quotes: "A *Clos* network is a kind of multistage circuit
switching network."
- **Words as words**: italicize when referring to the word itself: "Use the
word *and* instead." Don't use bold or quotation marks.
- **Titles of full-length works**: italics (*The Chicago Manual of Style*).
Short works get quotation marks.
- Don't use italics for emphasis in running text; prefer plain words or
reordering.
|
