--- title: "Persons" canonical: "https://documentation.chaos.com/space/DOCSGUIDE/623280131/Persons" format: markdown --- In grammar, *person *refers to the point of view represented by a statement and determines which pronoun to use. ## **General Rule** --- When writing **software descriptions**, make the software the doer of the action whenever possible. If the construction is too complicated or you need to avoid passive voice, use a second-person pronoun instead. When writing **instructions**, **user manuals**, or **tutorials**, use second-person pronouns. When appropriate, omit “you can” and make the sentence imperative. > ℹ️ In product UI (microcopy), avoid using “you” and “your” in ways that sound like we're commanding people to do something rather than providing options for them to make their own choices. **Examples for software descriptions** :check_mark:** **Dirt map is a simple texture used for simulating a variety of effects, such as scratches. :check_mark:** **Radius determines the amount of area where Dirt effect is produced. :cross_mark:** **We can determine the amount of area where the Dirt effect is produced using the Radius option. :cross_mark:** **Radius allows us to determine the amount of area where Dirt effect is produced. :cross_mark:** **Radius enables you to determine the amount of area where the Dirt effect is produced. (Note that in some specific cases, *enables you to* can be used) **Examples for instructions, user manuals, tutorials** :check_mark:** **Use a Dirt map to simulate scratches on the car. :check_mark:** **You can use a Dirt map to simulate scratches on the car. :cross_mark:** **We can use a Dirt map to simulate scratches on the car. ## **Software as Doer** --- The software should usually be presented as performing the action when writing feature descriptions. However, there are exceptions to this rule, such as when this would require passive voice or when the sentence structure would become too complicated for beginners. But apart from these exceptions, always try to make the software the subject of the sentence when describing features in the standard documentation. When using verbs such as ***enables ***or ***allows***, avoid making the software the subject of the sentence. In such cases, focus on what the user can do, not what the software does for them. It's OK to use “allows”* *to refer to features, such as security, that permit or deny some action or access. **Examples** :cross_mark: Microsoft Edge enables you to take notes. :check_mark: Write, draw, and take notes on webpages with Microsoft Edge. ## **Second-person pronouns (you, your)** --- In the second person, you write as though you're speaking to the reader. The second person often uses the personal pronoun “you”* *or “your”, but sometimes the word “you”* *is implied. It supports a friendly, human tone and helps avoid passive voice by focusing the discussion on the reader. Omit “you can” whenever the sentence works without it. **Examples** :check_mark: ~~You can ~~Check if you have local admin rights. (becomes an imperative sentence when you omit *you can*) :check_mark: Depending on your choice, some features may be turned off by default. :check_mark: Change your settings. ## **Singular first-person pronouns (I, me, my)** --- In first person, you write as though you’re speaking from the reader’s point of view. Marketing and support documentation should **never use** first person singular. ## **Plural first person (we, us)** --- First-person plural, which often uses the pronoun “we”, can feel like a daunting corporate presence. It's OK to use phrasing like “we recommend” if it helps you avoid awkward phrasing like “it is recommended”, but write around it if you can. Try to keep the focus on the customer, not Chaos. It’s OK to use “we” in privacy and security settings when you need to make it clear that Chaos is the speaker. **Examples** :check_mark: Notify scheduled default setting is the easiest way to keep your plugin up to date. (Instead of “We recommend that you use the scheduled default setting ....”) :check_mark: Change your password (Instead of “We recommend that you change your password.”) :check_mark: We protect your privacy at every step. ## **User, End user** --- Don't use “end user”. Avoid “user”* *when you can. Use “you”* *instead. > ⚠️ There are always exceptions to the general rule. Some cases may be unique and require nonstandard methods. ## **Reference** --- - Microsoft Style Guide: [https://learn.microsoft.com/en-us/style-guide/grammar/person](https://learn.microsoft.com/en-us/style-guide/grammar/person) - Developing Quality Technical Information - A Handbook for Writers and Editors - Stackoverflow: [https://stackoverflow.com/questions/2923114/using-the-word-you-in-an-user-manual](https://stackoverflow.com/questions/2923114/using-the-word-you-in-an-user-manual)