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.

Avoid anthropomorphisms

Anthropomorphisms attribute human characteristics to inanimate objects. Computers don't think, want, worry, or do other things that are uniquely human. In addition, anthropomorphisms can be imprecise, unclear, and do not translate well. Avoid anthropomorphisms in your writing to promote clear documentation written in plain language. For more information, see Use plain language.

Review the following table for examples of anthropomorphisms and how to rewrite them:

Do this Don't do this
The forwarder sends data to the location that you set in the configuration file. The configuration file tells the forwarder where to send the data.
Processing components process the data. Processing components handle the data.
The server sends a request to other parts of the network. The server wants to talk with other parts of the network.
The software creates a bucket for each unique IP address it detects. The software creates a bucket for each unique IP address it sees.
A receiver prepares to accept data that a forwarder sends to it. A receiver listens for data that a forwarder sends to it.
The metric shows how many CPU cores the process is using. The metric tells you how many CPU cores the process is using.

Writing with commonly used anthropomorphisms

Some anthropomorphic terms, like ingest and consume, are common in technical lexicon. You can include these terms in your writing if they are well understood by your audience. In general, strive to write clearly using plain language as much as possible.

See the following examples of acceptable anthropomorphisms:

  • Now the service can ingest data from a third-party source.
  • The service consumes data from the repository.
  • The process handles search requests.
  • The algorithm learns by estimating the coefficient values in the test set using the training set data.
  • A single search head manages searches and interacts with users.
Last modified on 09 July, 2024
Write in indicative or imperative mood   Write accessible documentation

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