Splunk® Style Guide

Splunk Style Guide

The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.

Be active and present

Strive for active voice and present tense in your documentation. Writing in active voice allows readers to place themselves as the subject in the documentation, and present tense tells readers what they can expect as they work through the topics.

While using passive voice and future tense is sometimes appropriate, keep your audience in mind by writing in plain language and centering your writing around the user as much as possible. For more information, see Use plain language.

Active voice

Active voice makes content clear by indicating who or what performs the action, even when the subject is implied. Minimize the use of passive voice in your writing.

Review the following table for examples rewritten to use active voice:

Do this Don't do this
Select Print to print the document. When the Print button is selected, the document is printed.
The forwarder sends data to the receiver. Data is sent to the receiver.

When is it okay to use passive voice?

Write in passive voice carefully and sparingly. The following examples describe situations where you might choose to use passive voice instead of active voice:

  • When you want to avoid placing blame on the user, such as in an error message
  • When defining the actor in the sentence is irrelevant or awkward

Present tense

Present tense allows readers to experience the documentation while they read it. Minimize the use of past tense or future tense in your writing.

Review the following table for examples rewritten to use present tense:

Do this Don't do this
The summary statistics continue to calculate allowed items, but the items don't appear in the dashboard. The tool processes all apps before they are published to Splunkbase.
All apps are processed through the tool before they are published to Splunkbase. The tool will now process all apps before being published to Splunkbase.
After the search is completed, the table updates automatically. After the search was completed, the table updated automatically.

When is it okay to use future tense?

Write in future tense carefully and sparingly. Do not use future tense if you can rewrite the sentence to use present tense instead. In general, strive to keep documentation timeless, and avoid writing about time-sensitive information that might become irrelevant in the near future. For more information, see Timeless.

The following examples describe situations where you might choose to use future tense:

  • In tutorial content, when describing what the reader will achieve during the tutorial part
  • In deprecation or end-of-life statements for a product
Last modified on 12 January, 2024
Use plain language   Write in indicative or imperative mood

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

Was this topic useful?

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