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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
# Formatting and organization detail
Detail for: headings, lists, tables, notices, links/cross-references, footnotes,
images, examples, procedures, paragraphs, UI elements, text formatting,
filenames. Source: developers.google.com/style (Headings, Lists, Tables,
Notices, Cross references, Footnotes, Images, Examples, Procedures, Paragraph
structure, UI elements, Text formatting, File names).
## Headings and titles
- **Sentence case** for all headings and titles (title case only for proper
product names).
- **Task-based headings**: start with a bare infinitive — "Create an instance",
not "Creating an instance".
- **Concept headings**: noun phrase, not an -ing verb — "Migration to Google
Cloud", not "Migrating to Google Cloud".
- One unique h1 per page; don't repeat the page title verbatim in a heading.
- Don't skip heading levels (h1 → h2 → h3 in order); headings need content
after them (no empty headings).
- Keep punctuation simple; no numbers to indicate sequence; no links in
headings; avoid code in headings (if needed, add a descriptive noun).
- Abbreviate in a heading only when the abbreviation is better known; define it
in the first paragraph after.
- Use "the following sections" when referring to a group of subsections
("The following sections describe the views in the data preparation editor").
## Lists
- Numbered lists: sequence matters (steps, phases, priorities).
- Bulleted lists: most other lists; parallel structure required.
- Description lists: term–definition pairs.
- Don't use a list for a single item.
- Introduce lists with a complete sentence, usually ending in a colon.
- List items: start with a capital letter; use periods if items are complete
sentences (or after each numbered step in a procedure); keep items parallel
(same grammar).
- Present each item as an equal alternative or sequence element — don't hide
steps inside other items.
- Sub-steps in procedures: use lowercase letters under a numbered step.
## Tables
- Use a table when each row has 3+ related pieces of information; lists for
simpler sets; description lists for pairs.
- Introduce with a complete sentence ending in a colon.
- Column headings: short, clear, sentence case, no ending punctuation.
- Keep cells short; avoid long sentences inside cells.
- Use proper table markup (caption, th with scope) for accessibility.
- Don't use tables for layout, code snippets, long one-dimensional lists, or
inside numbered procedures.
## Links and cross-references
- Link selectively; every link is a chance for the reader to leave. Provide
context on the page when a sentence or two suffices.
- **Descriptive link text**: the page title or a descriptive phrase; never
"click here", "this document", or a bare URL.
- Recommended: "For more information about task scheduling, see Reliable task
scheduling on Compute Engine."
- Not recommended: "Want more? Click here!"
- Use "For more information, see..." or "For more information about X, see..."
— never "on".
- One link to a destination per page (exceptions: very long pages, multiple
entry points).
- Don't open links in new tabs; if you must, say so ("opens in a new tab").
- Don't use external-link icons; mention "the Wikipedia page about..." in text
if the domain matters.
- Punctuation outside link tags where possible (`see <a>Test your code</a>.`).
- Unlinked references: short works in quotes, full-length works in italics.
- When linking a command or code item, include a descriptive noun in the link
text: "run the `gcloud instances create` command".
## Notices
- Four types: **Note** (useful, non-critical aside), **Caution** (proceed
carefully), **Warning** ("don't do this" / irreversible / data loss),
**Success** (interactive content only).
- Use notices sparingly — overuse makes readers skip them. Don't stack two
notices; rewrite instead.
- Don't use notes for cross-references, prerequisites, full steps, or
information the reader needs to succeed.
## Images
- Use images for UI elements and diagrams, not for text, code, or terminal
output.
- **Alt text** (always): concise (≤155 chars), descriptive, context-aware;
no "Image of..." or "Photo of..."; include punctuation; no all-caps.
- "Architecture of an app that's built with Apps Script."
- Decorative images: `alt=""` (still include the attribute).
- Introduce images with a complete sentence (colon if it immediately precedes,
period otherwise).
- Use high-resolution / vector images when practical; keep them sized to the
layout.
- Don't rely on screenshots of text that should be real text (accessibility).
## Examples
- Never use real PII: use reserved example domains (example.com, example.org,
example.net), fictional names (e.g. Alex, Dana), `dana@example.com`, example
phone numbers (800-555-0100 through 0199 range), `USER_ID` style placeholders.
- Introduce examples per the guidance in `format-examples`:
- End of sentence: comma or em dash; short mid-sentence ones in parentheses.
- Not recommended: "Enter a name for the instance, for example, my-instance-99."
- Recommended: "Choose a strong encryption algorithm, such as AES-256."
## Procedures (numbered steps)
- First sentence of each step contains an imperative verb: "Clone the
repository...", not "You need to clone..." (that's context, not a step).
- Complete sentences; parallel structure; consistent verb form.
- State location before action: "In the Google Cloud console, go to the
BigQuery page." not "Go to the BigQuery page in the Google Cloud console."
- State purpose/goal before the action: "To start a new document, click
File > New > Document."
- Optional steps: start the step with "Optional:".
- Advanced/non-default: "Advanced:" prefix; only-for-some: "Optional:".
- No directional language (above, below, left, right-hand side).
- Set context (tool/environment) in the first step; restate under new headings.
- Sub-steps: letters (a., b., c.) within a numbered step.
- Multi-action: "Click File > New > Document" (> separates related UI
interactions in one step).
## Paragraphs
- One idea per paragraph; 5–6 sentences max (shorter is better); a one-sentence
paragraph is fine.
- Put the most important information first in the paragraph.
- Left-align text; no forced line breaks, no justification.
## UI elements
- Refer to element by its visible label, in bold: "click **Save**", "the
**File** menu", "the **New project** window".
- Code-eligible elements (values you type) get code + bold: "In the
**Network** list, select `my-net-2`."
- Follow the label's capitalization, but normalize all-caps or inconsistent
labels to sentence case.
- Don't use UI elements as verbs/nouns in prose: "enter a name in the
**Service account ID** field" instead of "name the account".
- Keyboard keys in `<kbd>`: "press **Ctrl+S**" (letter keys uppercase,
modifiers spelled out: "Ctrl", "Alt", "Shift").
- Explain icons; avoid directional language ("the menu at the top right").
## Text formatting summary
- **Bold**: UI labels, and strong emphasis sparingly.
- **Italics**: new terms, words-as-words, titles of full works (see
grammar.md).
- **Code font**: anything the reader types or that is a code entity (see
code.md).
- No underlines for emphasis; no all-caps; no ampersand for "and" in prose.
- Sentence case everywhere; American spelling.
## File and directory names
- Lowercase, hyphens between words, ASCII only: `query-data.html`, not
`query_data.html` or `Query-Data.html`.
- No generic names (`document1.html`).
- Consistent with existing naming in the directory (exceptions allowed to stay
consistent).
- When referencing: code font + the word "file": "the `pg_hba.conf` file".
- File *types*: use formal names ("PNG file", not ".png file") — word list has
specifics.
|
