Manual names, topic titles, and section headings

Succinct and descriptive names for manuals, chapters, topics, and sections let a user know what they can expect to find in the content. Titles that include the product name tell readers which product they are in when they land on your topic from a search. Clear headings support every reader's ability to locate information on a page.

Best practices

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

• Include the product name in the topic title. If the product name is very long, use an approved abbreviation.
• Write titles and headings using words that are short, descriptive, and specific.
• 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", and use definitive language instead.
• Don't use special formatting in headings, such as monospaced font or italics.

Name your manual

Use headline-style capitalization for manual names. See Capitalization.

Create your manual name using an imperative statement with the product name. If the product name is very long, you can use the product abbreviation at the end of the title, as long as the abbreviation is approved.

Avoid terms such as "Guide" or "Manual" in the manual name, and find a descriptive verb to accompany the product in the manual name instead. You can also use a noun that describes the content, such as Release Notes, Scenarios, Tutorial, and API Reference.

When you refer to a manual name in Splunk documentation, format the manual name in italics. See Formatting reference.

Manual name examples

The following table shows examples of clear and descriptive manual names:

A clear, descriptive manual name	What makes this manual name good
Administer Splunk Enterprise Security	This name is a better option than something like "Admin Guide" because it is action-oriented and names the specific product it applies to.
Install and Upgrade Splunk Enterprise Security	This name is a better option than something like "Installation Guide" because it lets a reader know that it contains both installation and upgrade content for Splunk Enterprise Security.
Get Data Into Splunk User Behavior Analytics	This name is a better option than something like "Getting Data In" because it's imperative in tone for a specific product.
Use Splunk Enterprise Security Dashboards	This name is a better option than something like "Dashboard Manual" because it is action-oriented and names the particular product.
Integrate the Splunk App for Infrastructure with ITSI	This name is a better option than something like "Integrate SAI" because it tells the reader which products they can integrate.

The order of headings

Refer to the following terms when you create your manual:

Heading level	What it means
H1	The topic title
H2	Subheading
H3	A subsection within a subheading

Use only one H1 per page.

Follow the correct order of heading levels in Splunk docs: H1, H2, and then H3. Don't follow an H1 with an H3.

Don't nest content deeper than an H3.

Headings and text together

Always make sure that your headings are useful and descriptive.

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 heading with another heading, a list, a table, or an image.

There are times, however, when it's acceptable to follow an H1 with an H2 and have no intervening text, or to follow an H2 with an H3 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.

Name your topic or sections

Use sentence-style capitalization for chapter names, topic titles, and section headings. To determine what is capitalized if you have numerals or punctuation in a sentence-style heading, see Capitalization style definitions.

Include the product name in every H1. If the product name is very long, use an approved abbreviation. You don't need to repeat the product name in every H2 and H3 on a page.

Don't use numbers in headings to indicate a sequence unless you're listing parts of a tutorial. Only use numbers in a heading if they are part of a name, like "SPL2". See Numbers in 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	Examples
Task information	Imperative mood. Use command verbs in the present tense, such as "edit" or "modify".	Do this Configure correlation searches Don't do this Configuring correlation searches
Reference information	Noun phrase	Do this Search commands ITSI REST API reference Don't do this Using search commands Using the ITSI REST API reference
Conceptual information	Gerund phrase or noun phrase	Do this Installing Splunk Enterprise The redistribute command Don't do this 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, such as "troubleshoots" or "monitors".	Do this Scenario: Kai schedules a weekend shift Scenario: Sasha investigates performance issues Don't do this Use case: Schedule a weekend shift Investigate performance issues

Topic title and section heading examples

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

Original title	A clearer, more descriptive title
Import entities	Import entities into ITSI from a CSV file
Use setup pages	Enable first-run configuration with setup pages in Splunk Cloud Platform or Splunk Enterprise
About the Splunk App for CEF	How the Splunk App for CEF works
Configure inputs	Configure inputs for the Splunk Add-on for AWS

Name your topic in the table of contents

Some Splunk docs authoring platforms allow you to use a name for your topic in the table of contents that is different from the topic title. It's okay to abbreviate long topic titles in the table of contents (TOC) by leaving out the product name, but don't change the primary verb and object of the title. If the name in the TOC is too different from the topic title, readers aren't sure if they're in the right topic when they select one in the TOC.

Mood and phrasing cue the reader into the type of content they're about to read, so don't change the mood or phrasing of the topic title in the TOC. 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.

The following table shows examples of topic titles and correct and incorrect examples of TOC names:

Topic title	Correct example of TOC name	Incorrect example of TOC name
Install the Browser RUM agent for Splunk RUM	Install the Browser RUM agent	Install the instrumentation
Configure the Splunk Browser RUM instrumentation	Configure the instrumentation	Configuring instrumentation
Manually instrument browser-based web applications	Manually instrument the application	Manual instrumentation
Add navigation to an app in Splunk Cloud Platform or Splunk Enterprise	Add navigation to an app	Adding navigation

Context-friendly headings

Write headings that users can understand without the context of the surrounding topics or related sections, and consider what happens if they land on a topic from a search. For example, don't include numbered steps in titles or headings, such as "Step 5: Move the cursor" because it relies on the topics around it. A supertask might be a better way to organize your content than to include numbered steps in the title or heading.

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.