Headings

Table of Contents

Overview

Write all documentation headings in sentence case and, in most cases, use an imperative verb, as the majority of our documentation instructs readers to do something. If the topic discusses other information, such as a primer on a module or other informational content, an imperative verb isn’t required since the reader isn’t being instructed to do something. A descriptive heading will suffice.

Exception: For other documents and writing, such as HR policies or marketing collateral, write titles in title case. Imperative verbs aren’t required but can be used depending on the subject matter and purpose of the document. These guidelines are mandatory for BriteCore help site documentation.

Exception: For advanced settings post titles, use only the name of the setting and remove the hyphens. Don’t begin advanced setting post titles with an imperative verb, and don’t include any other text. Use sentence case.

If a heading is immediately followed by lead-in/introductory text(not separated by other content), the lead-in text should provide additional information or otherwise vary from the text of the header. If it doesn’t, and solely restates the text of the heading, you don’t need it.

Example

Heading: Access the Contacts module

Lead-in text: To access the Contacts module…

In instances such as this, it’s acceptable to begin with step 1 after the heading. No lead-in text is necessary as it’s repetitive and serves no function.

Example

Heading: Access the Contacts module

Lead-in text: The Contacts module is BriteCore’s central repository for managing and editing contacts. Access the Contacts module by…

Lead-in text is appropriate in this context because it provide additional information beyond what the heading states.

Use your best judgment during your writing. Any issues or concerns will be addressed in editing.

Heading 2s

For documentation, which is all housed here in WordPress, the highest heading level is heading 2. Heading 1 formatting is automatically applied to all post and page titles. When a heading 2 precedes/introduces steps, use an imperative verb (a command verb that tells the reader to do something). If a heading 2 serves as an overview where its subordinate heading 3s precede/introduce instructions/steps, the heading 2 can be descriptive, and make the heading 3s imperative.

Exception: For other documents and writing, such as HR policies or marketing collateral, write titles in title case. Imperative verbs aren’t required but can be used depending on the subject matter and purpose of the document.

Examples

  • Add a contact
  • Submit a claim
  • Create an email alert
  • Contacts
  • Claims
  • Alerts

After the heading 2, you should generally include a brief introductory sentence or paragraph that provides the reader with context or other useful information. In general, for documentation, don’t follow a heading with another heading.

Heading 3s

When a heading 3 precedes/introduces steps, use an imperative verb. If a heading 3 serves as an overview where its subordinate heading 4s precede/introduce instructions/steps, the heading 3 can be descriptive, and make the heading 4s imperative.

Examples

  • Add a contact
  • Submit a claim
  • Create an email alert
  • Usage considerations
  • Contacts permissions

Heading 2s in single- versus multi-topic documents

Don’t include a heading 2 in single-topic documents, as it will only repeat the text of the heading 1 (the page title). For documents with multiple subtopics, begin each with a heading 2 that uses an imperative verb.

Headings in multi-topic documents

For documents with multiple subtopics, begin each section with a heading 2 (and deeper heading levels, as applicable). Follow previous guidance regarding imperative/descriptive headings.

As previously mentioned, only include lead-ins after subheadings if they provide additional information, context, part of a step, or otherwise doesn’t simply restate the text in the heading.

Examples

Additional heading guidelines

Sometimes, a document will address additional considerations, usage considerations, etc. Use the title Additional considerations or Usage considerations, not Use considerations. Use considerations can be ambiguous in its meaning depending how the reader interprets the word use.

In addition:

  • Don’t bold headings; this is applied via the WordPress template styling.
  • Use sentence-style capitalization.
  • Don’t apply code formatting in headings, as this will negate the heading formatting. Only use code formatting in body text.
  • Try to avoid lengthy headings when possible.
  • Don’t end headings with punctuation.
  • Minimize use of en and em dashes.
  • Don’t use ampersands (&) or plus signs (+).
  • Break two-line headings thoughtfully.
  • Be clear and concise.
  • Focus on what matters to customers.
  • Use parallel structure when applicable.

For more information, visit the Microsoft Style Guide Headings page.

Table of Contents