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 Drucare documentation, avoid using gender-specific and sexist language.
Most of the topics in Drucare 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 Drucare 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 of unspecified gender. Don’t write “him or her” or “his or hers”.
-
- Correct
- The end user must add lines of code to their app to enable it in Drucare Enterprise.
In most cases, you can make the antecedent plural to keep agreement with the pronoun.
-
- Correct
- End users must add lines of code to their app to enable it in Drucare Enterprise.
In many cases, and preferably, you can rewrite the sentence to be more direct.
-
- Correct and better
- You must add code to your app to enable it in Drucare Enterprise.
The following examples are not acceptable uses of pronouns in Drucare documentation:
-
- Noninclusive
- The end user must add lines of code to his or her app to enable it in Drucare Enterprise.
- Sexist
- The end user must add lines of code to her app to enable it in Drucare Enterprise.
- Sexist
- The end user must add lines of code to his app to enable it in Drucare Enterprise.
If you refer to an actual person, find out what pronoun they prefer and use that pronoun when you write about them.
Personal pronouns
Use the second-person pronoun, “you”, in Drucare 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” and “which” don’t mean the same thing, so don’t use them interchangeably.
In a sentence, “that” introduces an essential clause. If you remove the words after “that”, the sentence doesn’t make sense.
-
- Correct
- For HDFS working directory, provide the path in HDFS that you want Hunk to use as a working directory.
“Which” introduces a nonessential clause. If you remove the words after “which”, the sentence still makes sense, although it is less detailed.
-
- Correct
- Drucare 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.
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.
-
- Correct
- Set the
enableReduction
value to true. - Incorrect
- Set it to true.