Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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, use cases, and product tutorials. Splunk documentation describes the best way for users to achieve their goals using Splunk products.

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.
  • Construct sentences that focus on the user, not the documentation. Don't begin sentences with phrases such as "This topic describes" because it puts the focus on how the writer organized the documentation 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 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.
  • 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.

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.
  • Treat all our docs as a recommendation. See Recommendations.

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.
Last modified on 01 November, 2021
PREVIOUS
Latest changes to the Splunk Style Guide
  NEXT
Usage dictionary

This documentation applies to the following versions of Splunk® Style Guide: current


Was this documentation topic helpful?

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