Using the word "you" in an user manual [closed]

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.

---

This question does not appear to be about programming within the scope defined in the help center.

Closed 8 years ago.

开发者_开发问答 Improve this question

I am writing a user manual and I have come to a discussion with a colleague. He says I cannot use the word "you" anywhere in the manual. Now I remember something about this at school but that was not for writing procedures. Also, doing some googling I observed that most tutorials where using it a lot. I would prefer using it but only if this is considered good practice. what do you think?

---

The alternatives that I know of are:

• 'You' (second person singular) - "You should put the plate on the table."
• Imperative - "Put the plate on the table."
• 'We' (first person plural) - "We should put the plate on the table."
• 'The user' (third person singular) - "The user should put the plate on the table."
• Passive - "The plate should be put on the table."

My own preferences are:

• I prefer the imperative as the default mode, because it's the briefest (least verbiage).
• I avoid the passive, and the first person plural.
• I use the second person pronoun ("you") or a third person noun (e.g. "your system administrator") when I want an explicit subject instead of the imperative.

---

Some people believe that manuals should be written as if they were scientific papers. Others believe that technical accuracy and readability is more important. I'm of the latter persuasion - use "you" if it fits with your overall style, but be consistent in your usage - I find documents that switches between "you" and "we" are irritating (and it's a sin I've been guilty of myself).

---

Which is easier to understand?

Click the button. You will see a dialog box where you can type your name.

or

The action of clicking the button will cause the appearance of a dialog box allowing the possibility for the user to enter his or her name.

The first is much easier to grasp. (Using "you" can sometimes be sloppy, but that tends to be in cases where it's used as a substitute for "one", or "some people", or "people in general". It's fine to use it where you are actually referring to the person reading the text.)

---

• If you want, you can avoid the you-style by writing in the passive/imperative style. You can also try the 'we' approach, but that might sound a bit childish. You're doing nothing wrong with using you though.
• To avoid writing in the you-style, use the passive/imperative style. The we-approach might also work, though it might sound a bit childish. There is nothing wrong with using you though.
• We can avoid writing in the you-style by employing the passive/imperative style. Or we could use the we-approach, though we might sound a bit childish. One could try the one approach, but risk sounding to stiff-upper-lip and alienating the reader. We don't mind using you once in a while, though.

I myself do prefer the second line. A series of commands is easier to follow then a story in the you-form.

---

You should be writing explantions in the third person.

The Java streams model is a classic Decorator pattern example.

You should write instructions in the second person, but even then, it's still not a good idea to refer to the reader as "you".

Create a constructor that can initialize lists based on a given list of lists.

Now, how did you feel after I issued 2 commands to you, my reader?

---

Technical Writing Enforce the rule of using passive text only. which mean avoiding "you" will be a good idea to stay in the safe side. that's based on how i do it personally.

---

I would do what Google, Microsoft, Yahoo, etc do. Here's a random Help page from Google:

http://mail.google.com/support/bin/answer.py?hl=en&answer=8494

shows that "you" is being used. You can check how Microsoft writes their User Manual too.

As a side note, I wouldn't use "I" or "we".

---

I think if you are providing imperatives, such as "Open the door", or otherwise directly addressing the reader, then you should use "you" instead of making yourself more difficult to comprehend by talking about some abstract user.

Even in scientific papers, some of the most formal writing I can think of, it is debatable whether or not I, we and other first person language is permissible. As much as high school grammar teachers might like you to think otherwise, there is no universally appropriate scheme.

---

I would say just be careful. It could come across as too casual. If the intended audience is business-y, I would avoid it. However, if it's a home user scenario or the marketing is casual (think Southwest Airlines), I'd say go with it.

Just don't overuse. Then it becomes taxing on the reader.

Sample of how it's intended to be used?

---

It all depends on the tone and style of your writing. Formal approaches discourage the use of "you". Personally, I like to use a style that is concise, to the point and relatively informal. I have no problem with the "you" word when used sparingly.

Avoid over usage as in:

When you want to start the application you have to enter your password and then you have to select the function you want to use.

---

From the Handbook of Technical Writing. 8th Edition (p. 262):

You can make sentences shorter by leaving out some articles(a, an, the), some pronouns (you, this, these), and some verbs, but such sentences may result in telegraphics style and be harder to understand.

So, I'd say it's OK to use you, but like Gilbert Le Blanc said in his comment, it's often better to write 'then click the button' instead of 'then you click the button'.

---

Impersonal form should be preferred. The use of 'you' would be too clear, and most of your clients will believe you are not professional. A clear manual will also reduce the need for post-sale customer support, and cause losses to the company.