Headings

Table of Contents

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.

If a heading is immediately followed by lead-in 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, you don’t need it. Don’t duplicate heading text in a lead-in.

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 1s

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

Examples:

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

After the heading 1, 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 2s

When a heading 2 precedes/introduces steps, use an imperative verb. 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.

Examples:

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

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, Microsoft offers solid advice about writing headings:

  • Think of headings as an outline and use judiciously.
  • Use sentence-style capitalization
  • Keep headings as short as possible.
  • Don’t end headings with a period.
  • Minimize use of hyphens.
  • Don’t use ampersands (&) or plus signs (+).
  • Break two-line headings carefully.
  • Be specific.
  • Focus on what matters to customers.
  • Use parallel structure.

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

Table of Contents