Headings and titles

Headings are the main way readers scan a page and the main way navigation is built from it. These rules cover how to phrase headings for tasks and concepts, how to format them, and how to keep a page’s heading hierarchy sound. General capitalization style lives on the capitalization page.

Start task headings with a verb

head-005 should GuidesAPI docs

Write task-based headings starting with a bare infinitive verb (‘Create an instance’).

Examples

• ✓ Create an instance
• ✗ How to create an instance

Rationale

A bare-verb heading such as “Create an instance” tells the reader what the section helps them do.

Conceptual headings as noun phrases

head-006 should GuidesAPI docs

Write conceptual or non-task-based headings as noun phrases that do not begin with an -ing verb.

Examples

• ✓ Access control options
• ✗ Understanding access control

Rationale

A noun-phrase heading signals a concept rather than a task, matching the reader’s intent.

No -ing openers

head-007 should GuidesAPI docs

Avoid using -ing verb forms as the first word in any heading or title.

Examples

• ✓ Monitor your instances
• ✗ Monitoring your instances

Rationale

An -ing opener translates inconsistently and reads less directly than a bare verb or noun phrase.

Parallel structure

head-003 should GuidesAPI docs

Use parallel writing structures for similar items such as lists. If using parallel structure on a heading results in awkward writing, don’t use parallel structure for that particular heading.

Examples

• ✓ Sibling headings “Create a key”, “Rotate a key”, “Delete a key”
• ✗ Sibling headings “Create a key”, “Rotating keys”, “How to delete your key”

Rationale

Parallel phrasing across similar items lets a reader scan them as a set.

Marking optional sections

head-015 should GuidesAPI docs

Use the ‘Optional:’ prefix in a heading (rather than parenthetical notation) to signal that a section is not required for all users.

Examples

• ✓ ## Optional: Configure a custom domain
• ✗ ## Configure a custom domain (optional)

Rationale

A leading “Optional:” is visible while scanning headings, unlike a trailing parenthetical.

Capitalization after a colon

head-001 should GuidesAPI docs

In a title or heading, capitalize the first word after a colon. This is an exception to the body-text convention, where the word after a colon is lowercase unless it is a proper noun, a quotation, or follows a label such as Note or Caution.

Examples

• ✓ Quickstart: Create your first app
• ✗ Quickstart: create your first app

Rationale

A heading is a title, so its first word after a colon is capitalized, unlike body text.

No trailing periods

head-002 should GuidesAPI docs

Do not end headings with periods.

Examples

• ✓ Install the CLI
• ✗ Install the CLI.

Rationale

A heading is a label, not a sentence, so a period adds visual noise without meaning.

Code items in headings

head-011 should GuidesAPI docs

Avoid code items in headings; if a code item must appear in a heading, accompany it with a descriptive noun in code font.

Examples

• ✓ ## The fetch() function
• ✗ ## fetch()

Rationale

Code font in a heading fights the heading style and often renders poorly; a descriptive noun reads better.

Define abbreviations below the heading

head-013 should GuidesAPI docs

If an abbreviation appears in a heading or page title, define it in the first paragraph following the heading rather than relying on the heading alone.

Examples

• ✓ ## Configure CORS followed by “Cross-origin resource sharing (CORS) lets a page request resources from another domain.”
• ✗ ## Configure CORS followed by a paragraph that never spells out CORS

Rationale

A heading is scanned out of context, so an abbreviation’s definition belongs in the first paragraph where the reader can see it.

No section numbers

head-010 should GuidesAPI docs

Do not use numbers in headings to indicate a sequence of sections; rely on heading hierarchy and order instead.

Examples

• ✓ ## Configure the server
• ✗ ## 3. Configure the server

Rationale

Hard-coded section numbers drift when sections are added or reordered, while hierarchy conveys order on its own.

No links in headings

head-009 should GuidesAPI docs

Do not place links inside headings.

Examples

• ✓ ## Authentication, with the link in the paragraph below it: “For setup steps, see Configure authentication.”
• ✗ ## Authentication

Rationale

A link inside a heading competes with the heading’s job of labeling and can render oddly.

Use real heading elements

head-004 should GuidesAPI docs

Use heading elements/styles to communicate content hierarchy; do not use visual text formatting as a substitute for heading levels.

Examples

• ✓ ## Authentication
• ✗ Authentication

Rationale

Real heading elements convey hierarchy to assistive tech and tooling; bold text only looks like a heading.

One h1, no skipped levels

head-008 should GuidesAPI docs

Each page should have exactly one unique level-1 heading (h1), and heading levels should not be skipped.

Examples

• ✓ One # page title, ## sections, ### subsections — no level skipped
• ✗ A # page title followed directly by a ### subsection

Rationale

A single top-level heading and unbroken levels give assistive tech and readers a coherent outline.

No empty headings

head-012 should GuidesAPI docs

Do not use empty headings; every heading must be followed by content.

Examples

• ✓ ## Prerequisites followed by “You need a project with billing enabled.”
• ✗ ## Prerequisites followed immediately by ## Install the SDK

Rationale

A heading with nothing under it promises content that is not there.

Introducing subsections

head-014 should GuidesAPI docs

Use the phrase ‘the following sections’ (not ‘this section’ or ‘these sections’) when introducing a group of related subsections.

Examples

• ✓ The following sections describe each authentication method.
• ✗ These sections describe each authentication method.

Rationale

“The following sections” is unambiguous about direction when read linearly, unlike “this section.”

Stable anchor IDs

head-016 should GuidesAPI docs

If HTML anchors are permitted on your documentation platform, add custom anchor IDs to headings using lowercase letters and hyphens between words, and preserve old anchor IDs when revising headings to prevent broken links. In HTML, use a section element with an id attribute rather than an <a name> element. When a heading’s anchor was auto-generated, add a custom anchor using the old ID string so existing inbound links keep working.

Examples

• ✓ <section id="create-an-instance">
• ✗ <a name="CreateAnInstance">

Rationale

Stable, lowercase-hyphenated anchors keep inbound links working when a heading’s text changes.