A word about Splunk docs

Splunk documentation comes in a variety of forms and topic types. The Splunk docs set includes step-by-step instructions, conceptual content, reference guides, troubleshooting pages, scenarios, and product tutorials. Splunk documentation describes the best way for users to achieve their goals using Splunk products.

Every topic focuses on the user. By providing relevant information that guides a reader through a process or goal, Splunk docs help users become productive and confident when they use Splunk software.

To support this goal, Splunk documentation follows these principles:

• Focus on what the user can do, not on the product or a feature.
• Include only the information a user needs to accomplish their goal.
• Write in direct, plain language.
• Include rich examples that help users understand complicated concepts or complex procedures.
• Write content that stays relevant over time.

User-focused

Readers look for content that applies to their situation, so Splunk docs avoid describing what the product or UI does and instead focus on what the user can do.

Apply the following guidelines to keep Splunk docs user-focused:

• Consider assumptions about the audience's knowledge level. Write documentation at the level of understanding the user has, but don't assume that terms and concepts are commonplace.
• Construct sentences that explain what the user can do with the product, not what the product lets the user do. Avoid starting sentences with phrases such as "This product allows you to", "This feature enables you to", or "This component lets you". Instead, construct sentences in a way that describe what a user can do with Splunk products and its features.
• Construct sentences that focus on the user, not the documentation. Don't begin sentences with phrases such as "The purpose of this document is" or "This topic describes" because it puts the focus on how the documentation is organized instead of what the user wants to do.
• Consider a reader's reason for using the documentation and focus the documentation on their goal rather than detailing every aspect of what engineering built.

Goal-oriented

Readers have more interest in achieving a goal than reading about a feature's capabilities. Splunk docs show a user how to complete goals and solve real-world use cases and scenarios.

Apply the following guidelines to keep Splunk docs goal-oriented:

• Identify your audience and know their needs before you plan your content.
• Describe prerequisites or background information about the feature that a user needs in order to achieve their goal.
• Include only the information that offers value to the reader in achieving what they set out to do. Link judiciously to supporting material or additional information. See Best practices for including links.
• Avoid documenting how to use the UI unless you think the user might have trouble figuring it out. Consider what a user can discover on their own by exploring the product.
• Don't include frequently asked questions (FAQs). A list of questions and answers in random order does not support user goals. Instead, incorporate the information into the relevant topic that describes how to accomplish the user's goal.

Straightforward

Readers don't read a manual from start to finish. Instead, they look for a title that matches their scenario, and then they scan the content for digestible information or relevant examples. Splunk docs have titles that are descriptive and tasks that are written in plain language.

Apply the following guidelines to keep Splunk docs straightforward:

• Title your topic and section headings in a way that readers can find the information they need.
• Write directly and in plain language. Avoid unnecessary technical language.
• Don't use industry-speak or jargon. Remember that people read Splunk docs all over the world and have varying reading comprehension levels.
• Treat all our docs as a recommendation. See Treat Splunk documentation as a recommendation.

For more information about writing in Splunk tone, see Splunk voice and tone. For guidance on topic titles, see Manual names, topic titles, and section headings.

Rich in examples

Readers look for examples that illustrate abstract concepts or complex procedures. Splunk documentation uses inline and extended examples to provide relevant and helpful content that's tailored to its target audience.

Inline examples

An inline example is a sentence containing an example that follows an abstract concept or complex procedure. Inline examples clarify meaning instead of making a reference to an obscure analogy. A typical inline example starts with "For example," and includes a brief statement that describes a relevant scenario for the user.

Extended examples

An extended example is composed of multiple sentences that walk a user through a common scenario. Extended examples can contain relevant and up-to-date images. A typical extended example takes the form of a subheader labeled "Example" that stands on its own in a topic.

Timeless

Readers expect to read documentation that provides precise and accurate information any time they access it. Splunk docs stay relevant by always being current and avoiding information that is expected to quickly change or expire. Apply the following guidelines to keep Splunk docs timeless:

• Avoid using words like "now", "new", "currently", "in the future", and "does not yet".
• Avoid writing about time-sensitive information that you expect to become irrelevant in the near future, such as mentioning beta releases or private previews. If you must include this information for clarity, update your content after it becomes obsolete.
• Don't expose information about Splunk products that isn't public knowledge, such as information about future releases, plans, or deprecations before they actually happen.