Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Recommendations

Readers come to Splunk documentation looking for the best way to use their product to achieve a goal. To accommodate this use, treat all of our documentation as a recommendation. Don't make specific recommendations, but instead guide the reader to the best choice using concrete language and direct instructions.

When you want to state a preference or a recommendation, apply the following guidelines in the documentation:

  • Offer users encouragement, best practices, and the optimal way to use their product for their specific use case.
  • Don't use phrases like "It is recommended to", "Splunk recommends", or "We recommend". Instead, rephrase recommendations as requirements or best practices.
  • Explain the reason why something is recommended instead of stating that it's recommended.
  • Use callout boxes to bring attention to important information that a user needs to be aware of, such as how to avoid data loss, but don't document worst-case scenarios or situations a user can avoid.
  • Include prerequisites, requirements, and decision support when necessary.
  • If there are multiple ways to do something, phrase the recommended way as an imperative statement and place that method before the other options.

Examples

Writing factual, direct statements helps a user understand why an option is a good idea and whether it applies to them. See the following examples:

Correct Incorrect
To minimize system impact, perform this action outside of normal business hours. It is recommended to perform this action outside of normal business hours.
Concealing specific values in spans is the best way to hide sensitive information in spans. We recommend concealing specific values in spans.
Take the time to learn which indexes contain your data, the sources of your data, and the source type of that data. Knowing this information helps you narrow your search results. Splunk recommends that you take the time to learn which indexes contain your data, the sources of your data, and the source type of that data.
Last modified on 06 October, 2021
PREVIOUS
Pronouns
  NEXT
Standard English spelling and phrases

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