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.|
|Conditional step||Phrase the step using an if statement.|
|Optional step||Preface the step with the word "Optional" in parentheses.|
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:
- In the time range picker, change the time range to Yesterday.
- Run the following search:
sourcetype=access_* status=200 action=purchase categoryId=simulation
- Find the number of purchases for each type of product.
categoryId=simulationfrom your search criteria and run the search again.
- Locate the unique categoryId values by selecting the categoryId field in the Selected Fields list.
- 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.
- (Optional) For the number of purchases made each day of the previous week, run the search again for each time range.
This documentation applies to the following versions of Splunk® Style Guide: current