Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

Numbered lists

When you write Splunk documentation, use numbered lists, sometimes called ordered lists or task lists, when the order of the list items is important. For example, you can use numbered lists to organize procedural information or sequential steps a user must follow. If you add substeps, use an ordered list marked by lowercase letters. If you need to describe a set of options for a list item, use a bulleted list or a table.

Qualities of numbered lists

Numbered lists must have the following qualities:

  • A complete lead-in sentence that describes the list's purpose, punctuated by a period or a colon
  • More than 1 list item
  • No more than 1 sublist for each list item if needed, with at least 2 items in a sublist
  • 1 action for each list item
  • Parallel sentence construction
  • Sentence case capitalization
  • End punctuation if the list items are complete sentences
  • No end punctuation if the list items are characters, words, or phrases

Avoid including links to other topics in task steps, unless in the case of a supertask, which is a numbered list composed of links to a series of tasks. See Best practices for including links. For more guidance on using lists, see Best practices for writing with lists.

Formatting task steps

When you're writing task steps, follow these guidelines to accurately describe and format the step:

Type of task step Guidance Example
Required step Write in the imperative mood.
  1. Log in to your instance.
Conditional step Phrase the step using an if statement.
  1. If you need to add an index to a single peer, create a separate indexes.conf file on the peer.
Optional step Preface the step with the word "Optional" in parentheses.
  1. (Optional) Create a splunk.com account.


The following example of a numbered list contains a heading describing the task and a complete lead-in sentence. Each item in the list contains a single action and uses parallel construction. In step 3, the procedure has substeps marked by lowercase letters. In step 4, the example shows an optional step.

Search for sales of a specific product

Follow these steps to search for how many simulation style games were bought yesterday:

  1. In the time range picker, change the time range to Yesterday.
  2. Run the following search:

    sourcetype=access_* status=200 action=purchase categoryId=simulation

  3. Find the number of purchases for each type of product.
    1. Remove categoryId=simulation from your search criteria and run the search again.
    2. Locate the unique categoryId values by selecting the categoryId field in the Selected Fields list.
    3. Select a categoryId name. The categoryId is added to your search and the search is automatically run again. The results show the number of purchases for that product.
  4. (Optional) For the number of purchases made each day of the previous week, run the search again for each time range.
Last modified on 28 November, 2023
Bulleted lists   Definition lists

This documentation applies to the following versions of Splunk® Style Guide: current

Was this topic useful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters