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.