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 ideal 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:

• Tell users the optimal way to use their product for their scenario.
• Don't use phrases like "It is recommended to", "Splunk recommends", or "We recommend". Instead, rephrase recommendations as requirements.
• Avoid quantifiable claims, such as "It is best to…", because these kinds of statements can be construed as provable or disprovable when compared to another method.
• 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 ideal way as an imperative statement and place that method before the other options. Explain the reason why one choice is optimal instead of stating that it's recommended.

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	Reason for the change
To minimize system impact, perform this action outside of normal business hours.	It is recommended to perform this action outside of normal business hours.	The example in the Do this column avoids a passive, vague recommendation and uses clear, actionable instruction.
Ideally, use spans to conceal specific values.	We recommend concealing specific values in spans.	The example in the Do this column replaces an explicit recommendation with neutral, reader-focused guidance.
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.	The example in the Do this column keeps the focus on the user, not the company, and removes unnecessary attribution. It also explains why the action is important, which helps the reader understand the value and context of the instruction.
Contact your Splunk representative if your requirements are different or exceed what is described in this table.	Contact your Splunk representative if your requirements are different or exceed what is recommended in this table.	The word "described" in the Do this column doesn't make claims about the product, unlike the word "recommended".
Use a SAML2 provider to give the optimal protection and security options for your authentication needs.	It is best to use a SAML2 provider to give the best protection and security options for your authentication needs.	The word "optimal" in the Do this column is more ideal than "best," which can be construed as provable or disprovable. This example also avoids passive phrasing.