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.

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 documentation as a recommendation. Don't make specific recommendations, but instead guide the reader to the best choice using concrete language and direct instructions.

Best practices

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 scenario.
  • 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:

Do this Don't do this
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 31 January, 2024
Pronouns   Including images in Splunk docs

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