diff options
Diffstat (limited to 'skills/google-style-guide/reference/formatting.md')
| -rw-r--r-- | skills/google-style-guide/reference/formatting.md | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/skills/google-style-guide/reference/formatting.md b/skills/google-style-guide/reference/formatting.md new file mode 100644 index 0000000..aa15763 --- /dev/null +++ b/skills/google-style-guide/reference/formatting.md @@ -0,0 +1,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.
\ No newline at end of file |