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 the reader's ability to locate information on the page quickly.
- Include the product name in the topic title. If the product name is too 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
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, Use Cases, Tutorial, and API Reference.
Use headline-style capitalization for manual names. See Capitalization.
Manual name examples
The following table shows examples of good manual names:
|Original name||A clearer, more descriptive name|
|Admin Guide||Administer Splunk Enterprise Security|
|Installation Guide||Install and Upgrade Splunk Enterprise Security|
|Getting Data In||Get Data into Splunk User Behavior Analytics|
|Dashboard Manual||Use Splunk Enterprise Security Dashboards|
|Integrate SAI||Integrate the Splunk App for Infrastructure with ITSI|
|Search Data||Search and Visualize Data with Splunk NLP|
The order of headings
Refer to the following terms when you create your manual:
|Heading level||What it means|
|H1||The topic title|
|H3||A subsection in 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 place content deeper than an H3.
Headings and text together
Make sure that text follows every topic title or section heading.
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.
Everywhere you can, provide important information the reader needs to know in the text between headings. Always make sure that your headings are useful and descriptive.
Name your topic or sections
Include the product name in the topic title. If the product name is too long, use an approved abbreviation.
You don't need to include the product name in every H2 and H3.
Use sentence-style capitalization for chapter names, topic titles, and section headings. See Capitalization.
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. Use command verbs in the present tense, such as "edit" or "modify".||
|Reference information||Noun phrase||
|Conceptual information||Gerund phrase or noun phrase in the declarative mood||
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|
|Create and manage apps||Create and manage apps for Splunk Cloud Services|
|About the Splunk App for CEF||How the Splunk App for CEF works|
|Configure inputs||Configure inputs for the Splunk Add-on for AWS|
Write headings that users can understand without the context of the surrounding topics or sections. For example, don't include numbered steps in titles or headings, such as "Step 5: Move the cursor." 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 form sparingly.
Documenting third-party products
UI text style guidelines
This documentation applies to the following versions of Splunk® Style Guide: current