# Structured documents

For anything with sections: reports, READMEs, design docs, plans, specs,
runbooks, long PR descriptions. From the Google developer documentation style
guide; each section names its source page. A short chat reply needs none of
these structures; for short-form reporting, see "Reporting your own work" in
`SKILL.md`.

Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Contents

- [Headings](#headings)
- [Paragraphs](#paragraphs)
- [Lists](#lists)
- [Procedures](#procedures)
- [Notices](#notices)
- [Tables](#tables)
- [Introducing examples](#introducing-examples)
- [Links and cross-references](#links-and-cross-references)
- [Headings as link targets](#headings-as-link-targets)
- [Figures and images](#figures-and-images)
- [Footnotes](#footnotes)
- [Accessibility](#accessibility)

## Headings

Source: https://developers.google.com/style/headings

Sentence case. One h1. No skipped levels. Every heading followed by content,
never straight into another heading.

A task heading starts with a bare infinitive; a concept heading is a noun
phrase. Gerunds are out as the first word: they translate inconsistently and
cost characters.

| Recommended | Not recommended |
|---|---|
| Create an instance | Creating an instance |
| Migration to Google Cloud | Migrating to Google Cloud |
| Transfer data sets | Transferring data sets |
| Optional: Customize your alias | Customize your alias (optional) |

No numbers, links, or code items in headings, and no end punctuation. Define an
abbreviation in the first paragraph rather than in the heading. Keep headings
unique within a document, since they double as link targets. When a run of
subsections follows, introduce it with "the following sections".

## Paragraphs

Source: https://developers.google.com/style/paragraph-structure

Most important information first. One idea per paragraph; past five or six
sentences, look for the second idea and split. A one-sentence paragraph is fine,
and a longer one is fine if it stays on a single idea.

Left-align text, no centering, no full justification. Never force a line break
inside a sentence; breaks survive neither resizing nor larger text.

## Lists

Source: https://developers.google.com/style/lists

- **Numbered** when order matters: steps, phases, ranked items.
- **Bulleted** when it doesn't: options, examples, alternatives.
- **Description lists** for term-and-definition pairs.

Introduce a list with a complete sentence, not a fragment the items complete.

Recommended: "Use the **Submit** button for any of the following purposes:"
Not recommended: "Use the **Submit** button to:"

Capitalize the first word of each item unless case is significant. End items with
a period, except single words, items with no verb, code-only items, and bare link
text. Keep every item in the same grammatical shape. Never write a one-item list.

In running prose, use serial commas and don't end with "etc." Phrase the
introduction so the list is openly partial instead.

## Procedures

Source: https://developers.google.com/style/procedures

One action per step, imperative mood. Sub-steps take lowercase letters,
sub-sub-steps lowercase roman numerals. A single-step procedure is a bullet, not
a numbered list of one. Combine only trivial sequential clicks, with `>`: "Click
**File > New > Document**."

State the location before the action, so the reader isn't hunting mid-sentence:

| Recommended | Not recommended |
|---|---|
| In Google Docs, click **File > New > Document**. | Click **File > New > Document** in Google Docs. |
| To start a new document, click **File > New > Document**. | |

Put the result in the same step as the action: "Click **Run**. The query results
appear after the query runs."

Prerequisites go before the procedure, never as step 1. Mark an optional step with
a leading "Optional:".

## Notices

Source: https://developers.google.com/style/notices

Four kinds, in ascending severity:

- **Note**: relevant but not needed for the task at hand.
- **Caution**: proceed carefully.
- **Warning**: don't do this; irreversible, or costs data, money, or security.
- **Success**: confirms an action completed. Use it only in interactive or dynamic
  content; it isn't a severity level like the other three.

Use them sparingly. Never stack two. A notice is the wrong container for a
cross-reference, a prerequisite, or a step. Anything the reader needs to succeed
belongs in the main flow.

## Tables

Source: https://developers.google.com/style/tables

Use a table when each item carries three or more related pieces of data. Pairs belong in a description list; single columns belong in a bulleted list.

Don't use tables for layout, for code, inside a numbered procedure, or to split
one long list across columns. Avoid single-row tables.

Introduce every table with a complete sentence describing its purpose, since not
every screen reader announces a table. Sentence case in headers and cells, no end
punctuation in headers, header cells marked semantically, and no merged cells. Sort
rows logically or alphabetically.

## Introducing examples

Source: https://developers.google.com/style/format-examples

At the end of a sentence, introduce an example with a comma, parentheses, or an
em dash, but not a semicolon. Mid-sentence, keep it short and set it off with
dashes, commas, or parentheses. A long example becomes its own sentence starting
"For example".

| Recommended | Not recommended |
|---|---|
| Choose a strong encryption algorithm, such as AES-256. | Specify the region for deployment; for example, `us-central1`. |
| You can monitor various metrics—for example, CPU utilization, storage capacity, and active connections. | |
| Enter a six-digit hex number (for example, `228B22`), and then click **OK**. | Enter a name for the instance (for example, `my-instance-99`). |
| You can tag instances by environment. For example, you could use `env:prod` or `env:dev`. | |

Write *for example*, *such as*, or *like*. Never *e.g.* or *for instance*.

## Links and cross-references

Source: https://developers.google.com/style/cross-references

Phrase a cross-reference as "For more information, see [...]" or "For more
information about X, see [...]". Use *see*, not *refer to*.

Link text is either the target's exact title or a descriptive phrase with the
important words first. Never "click here", "this document", "this article", or a
bare URL.

| Recommended | Not recommended |
|---|---|
| For more information about task scheduling, see [Reliable task scheduling on Compute Engine]. | For more information on indexes, see [Manage indexes]. |
| Run the command with the [`--hostname` flag]. | Want more? [Click here!] |
| [Google Kubernetes Engine (GKE)] | [Google Kubernetes Engine] (GKE) |

Keep punctuation outside the link. Don't reuse identical link text for different
targets in one document. Links open in the current tab; if one must open
elsewhere, say "(opens in a new tab)". No external-link icons. If leaving the
site matters, say so in the sentence.

## Headings as link targets

Source: https://developers.google.com/style/headings-targets

Anchor IDs in lowercase with hyphens between words:
`introduction-to-everything`. In Markdown, `## Heading text {: #anchor-id }`; in
HTML, an `id` on a wrapping `section`, an `a name` element, or on the heading
itself.

When you rewrite a heading that already has an auto-generated anchor, keep the
old anchor ID so existing links still resolve.

## Figures and images

Source: https://developers.google.com/style/images

Every image needs alt text summarizing its intent; decorative images take empty
alt text. Images aren't translated and aren't read aloud, so any information they
carry must also exist in the text.

Alt text: write it so that replacing the image with its alt text leaves the
page's meaning intact. Under 155 characters, a full sentence or a noun phrase,
with punctuation so a screen reader pauses. No "Image of" or "Photo of", no
all-caps. Empty `alt=""` for decorative images. Decorative covers more than it sounds: a
screenshot showing a reader how to fill in fields, an icon in the UI, anything
there only to make the page look better, and any image that restates what the
text already says. Introduce a diagram in the
surrounding text, not in the alt text; where a description needs more than 155
characters, summarize in alt text and explain in the body.

Captions are optional. Put one in a `figcaption`, formatted "**Figure 2.**
Description."
Complete sentences with end punctuation, sentence case. Refer to a figure by
number, lowercase ("figure 2"), never by position: not "the image above".

Screenshots and diagrams: SVG where possible, PNG otherwise, MP4 rather than
animated GIF. Crop to what matters, keep OS and visual style consistent across a
document, and cover any personal data with a solid 100%-opacity block. Keep
embedded text short and in sentence case, and use numbered callouts rather than
dense annotation. For high-resolution variants use `srcset` with a `_2x` suffix,
where the 2x image is exactly twice the dimensions.

Videos and GIFs need captions, a transcript, or a description, and nothing should
flicker.

## Footnotes

Source: https://developers.google.com/style/footnotes

Avoid footnotes: they aren't accessible and they complicate localization. Use a
cross-reference, a note, or a parenthetical instead. If one is unavoidable, mark
it with a superscript number and put the text at the foot of the page.

## Accessibility

Source: https://developers.google.com/style/accessibility

- Sentences under 26 words.
- No double negatives, and no piling up exceptions.
- Define acronyms on first use.
- Descriptive, unique headings in a semantic hierarchy.
- One instruction per list item in a procedure.
- Don't rely on color, sound, position, or shape alone to carry meaning.
- Replace directional language: *preceding* and *following*, not *above* and
  *below*.
- Everything reachable by keyboard alone.