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

Pronouns

Pronouns replace nouns. When you use pronouns in your writing, make sure that the pronoun correctly refers to the noun it replaces, known as its antecedent.

Gender-neutral pronouns

Write for inclusivity and don't make assumptions about sex or gender. When you write Splunk documentation, avoid gender-specific and sexist language.

Most of the topics in Splunk documentation use the second-person singular pronoun, "you" and "your", to address a single user directly. If you have to write in the third person or refer to someone in the third person, make sure that you choose gender-neutral third-person pronouns, such as "they", "their", and "them".

In Splunk documentation, it's acceptable to use a plural pronoun with a singular antecedent when you refer to people. Use third-person-plural pronouns when you refer to a person. Don't write "him or her" or "his or hers".

Do this
The end user must add lines of code to their app to enable it in Splunk Enterprise.

In most cases, you can make the antecedent plural to keep agreement with the pronoun.

Do this
End users must add lines of code to their app to enable it in Splunk Enterprise.

In many cases, and preferably, you can rewrite the sentence to be more direct.

Do this
You must add code to your app to enable it in Splunk Enterprise.

The following examples are not acceptable uses of pronouns in Splunk documentation:

Noninclusive
The end user must add lines of code to his or her app to enable it in Splunk Enterprise.
Sexist
The end user must add lines of code to her app to enable it in Splunk Enterprise.
Sexist
The end user must add lines of code to his app to enable it in Splunk Enterprise.

If you refer to an actual person in your writing, ask for their pronouns and use those. Don't assume or guess.

Personal pronouns

Use the second-person pronoun, "you", in Splunk documentation. Avoid first-person pronouns, such as "I", "our", "us", and "we", unless you are responding to customer feedback or are writing a tutorial.

Relative pronouns

"That", "which", and "who" are relative pronouns and don't all mean the same thing.

That

"That" introduces an essential clause. If you remove the words after "that", the sentence doesn't make sense.

Do this
For HDFS working directory, provide the path in HDFS that you want Hunk to use as a working directory.

Which

"Which" introduces a nonessential clause. If you remove the words after "which", the sentence still makes sense, although it is less detailed.

Do this
Splunk Enterprise changes one of the default port settings in the server.conf file, which is one of the stanzas you copied but didn't edit.

Who

When referring to a person, use "who" instead of "that".

Vague pronouns

Avoid ambiguous references between a pronoun and its antecedent. Vague pronouns include "this", "that", "which", and "it". To add clarity, replace the vague pronoun with a noun.

Do this Don't do this
Set the enableReduction value to true. Set it to true.
Last modified on 31 January, 2024
PREVIOUS
Prepositions
  NEXT
Recommendations

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