Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

Best practices for writing with lists

Lists organize information so that readers can scan content faster. Avoid writing tasks in paragraph form.

When you include lists in your content, consider these best practices:

  • Introduce lists with a complete lead-in sentence.
  • Include more than one item in a list.
  • Use up to two levels in a list.
    • The second level is called a sublist.
    • Sublists must have more than one item.
  • Capitalize the first letter of every list item.
  • If the list items are complete sentences, include end punctuation.
  • If the list items are characters, words, or phrases, don't include end punctuation.
  • Use parallel sentence construction in list items. For example, start all list items with verbs, or end all list items with punctuation.
  • Avoid including links that move users away from a list of tasks.
  • If you must include a link, don't hyperlink the entire list item unless it's supertask information or a prerequisite.
  • Use lists in tables sparingly.

Use these best practices to make docs accessible for all audiences. For more guidance on making docs more accessible using lists, see Write accessible documentation.

Choose the best list

Choose one of three lists based on your content:

Type of list When to use More information
Bulleted list Use when the list item order isn't important, such as a list of options. See Bulleted lists.
Numbered list Use when the order of the list items is important or the user is following sequential steps, such as a task. See Numbered lists.
Definition list Use for a list of descriptions, definitions, associations, or explanations, such as a glossary or a set of terms. See Definition lists.
Last modified on 15 June, 2023
Best practices for linking to third-party websites
Bulleted lists

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

Was this documentation topic helpful?

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