Best practices

Follow these best practices when creating titles and headings in your content:

• Use sentence-style capitalization for titles and headings. See Capitalization.
• Write titles and headings using words that are short, descriptive, and specific.
• When possible, lead with a keyword.
• Include the product name in the topic title. If the product name is very long, use an approved abbreviation. If you're not sure whether an abbreviation is approved for use, check with the Information Architecture team.
• You don't need to repeat the product name in every section heading on a page.
• Focus titles and headings around what a user can do with the product. Stay away from creating titles and headings that describe a feature.
• Remove vague terms or phrases in titles and headings, such as "Other", "Miscellaneous", "Introduction", or "Before you begin". Use definitive language instead.
• Don't use special formatting in headings, such as monospaced font or italics.
• Don't use numbers in headings to indicate a sequence unless you're listing parts of a tutorial. See Using numbers in text.
• You can write topic titles or section headings in the form of a question.

The order of headings

Use only 1 topic title per page.

Aim to use second-level subheadings as the deepest level in your topic.

Use third-level subheadings only if all of the content must be on the same page and can't be promoted to the second level.

If you need to nest content beyond the third level, create a separate topic and link to the new topic from the previous topic.

Moods and phrases for topics or section headings

As a guideline, use the following moods and phrases in your titles and headings for the type of content you're writing:

Type of content	Mood or phrase to use	Do this	Don't do this
Task information	Imperative mood. Use command verbs in the present tense.	Configure correlation searches	Configuring correlation searches
Reference information	Noun phrase	Search commands ITSI REST API reference	Using search commands Using the ITSI REST API reference
Conceptual information	Gerund phrase or noun phrase	Installing Splunk Enterprise The redistribute command	How to install Splunk Enterprise Use the redistribute command
Scenario-based content	Third-person point of view. Use indicative verbs after a persona's name.	Scenario: Kai schedules a weekend shift Scenario: Sasha investigates performance issues	Use case: Schedule a weekend shift Investigate performance issues

Examples of topic titles and section headings

The following table shows examples of good topic titles and section headings:

Include a lead-in sentence after a title or heading

After every topic title or section heading, include a line of text that provides information that the reader needs to know. In most cases, don't follow a topic title or second-level heading with another heading, a list, a table, or an image.

There are times, however, when it's acceptable to follow a topic title with a second-level heading and have no intervening text, or to follow a second-level heading with another section heading and have no intervening text:

• In a reference topic, such as a glossary of terms or commands.
• In a task, when the text between the heading and the numbered task steps merely repeats the heading.

Naming your topic in a table of contents

In most cases, use the same title for both the topic title and the title that appears in the guide's table of contents (TOC).

Some Splunk docs authoring platforms let you use a different name in a TOC. If you need to abbreviate the topic title in the TOC, make sure it aligns closely with the topic title.

If the name in the TOC differs significantly from the topic title, readers aren't sure if they're in the right topic when they select one in the TOC.

Follow these guidelines when abbreviating your topic title in the TOC:

• Don't change the primary verb and object of the title.
• It's okay to remove the product name to shorten the topic title.
• Don't change the mood or phrasing of the topic title in the TOC. Mood and phrasing cue the reader into the type of content they're about to read.

For example, if the topic title is written in the imperative mood, don't rephrase the title as a noun phrase or gerund in the TOC.

Can I write a title or heading in the form of a question?

You can write topic titles or section headings in the form of a question, but use this format sparingly.