Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


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.
Acrobat logo Download topic as PDF

Splunk voice and tone

The way you speak and the way you write is likely very different. Traditional technical writing tends to be dry and formal, whereas conversational language is often verbose or colloquial. Splunk documentation finds a balance between the two: Splunk docs are casual and approachable, yet succinct and direct.

When you create written content, shape your docs around your reader's needs and expectations, and write to them as though they are a professional acquaintance. Aim to be confident, friendly, and comprehensive, and not insensitive, saccharine, or complicated.

Here are a few guidelines you can follow to achieve a balanced tone in your writing:

  • Avoid jargon or idioms. See Use plain language.
  • Write in active voice and present tense whenever possible. See Be active and present.
  • Write in the indicative and imperative mood, and avoid using the subjunctive mood. See Write in indicative or imperative mood.
  • Avoid attributing human characteristics to inanimate objects. See Avoid anthropomorphisms.
  • Use contractions, such as isn't, don't, and can't. See Contractions.
  • Write precisely and concretely.
  • Avoid qualitative language, such as calling things easy or simple. What's easy for one user might be challenging for another.

Examples

The following table shows examples of writing that are too formal, too casual, and just right:

Too formal Too casual Just right
Note that Splunk Enterprise Security automatically enables SSL; therefore, confirm that the protocol in your web browser is "https" (for example: https://splunkserver:8000). ES enables SSL, so you might want to make sure that your web browser is using HTTPS, like in https://splunkserver:8000. Splunk Enterprise Security enables SSL. Check that the web browser protocol uses HTTPS. For example, https://splunkserver:8000.
Please select the Complete button to complete the process and display the result. When you select Complete and you see the result, you know you are done. Way to go! Select Complete.
The information about the KV store status can be retrieved from the kvstore/status endpoint via the GET method. Do a GET on the kvstore/status endpoint. Submit a GET request to the kvstore/status endpoint to access KV store status information.
Forwarder management is a graphical user interface (GUI) that is built on top of the deployment server and offers a streamlined solution to configure the deployment server and monitor the status of deployment updates. The forwarder management GUI lives on top of the deployment server. The GUI makes it easy to configure your server while monitoring any updates that might come up. You can configure the deployment server and monitor the status of deployment updates with the forwarder management graphical interface.
Metrics can be used for the investigation, monitoring, and troubleshooting of your pipeline in real time. You can use metrics to do some really cool things like look into, keep an eye on, and tweak your pipeline as the data is coming in. Use metrics to investigate, monitor, and troubleshoot your pipeline in real time.
A gauge is a metric that is composed of a single numerical value that can arbitrarily increase or decrease depending upon the value of which the metric is tracking. A gauge is a number that can go up and down for a couple of reasons, like if it gets hotter or colder in a server room. A gauge represents a single numerical value that changes based on what you're tracking.
Last modified on 12 January, 2024
PREVIOUS
Usage dictionary
  NEXT
Use plain language

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