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, use cases, and product tutorials.

Every topic type has a clear and honest focus 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 the user, 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.

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 help 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.
• 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 problems.

Apply the following guidelines to help 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.

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 help 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.

For more information about writing in Splunk tone, see 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 docs have two types of examples that are relevant, helpful, and tailored to its target audience.

Inline examples

An inline example 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 walks a user through a common use case. 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.