# 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.