Anthropomorphisms attributes 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:
|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.
Write in indicative or imperative mood
Write accessible documentation
This documentation applies to the following versions of Splunk® Style Guide: current