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

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?

Keenan

I've written code that engaged the user in a Q & A dialog. I wrote it with "I" and "you" because it felt right. It seemed to work well. Passive voice is for the passive, and often drops readability and comprehension as it often requires circumlocution. – Hbomb

Wow seems I had a great question going and they closed it. If this is not a SO question then why are the tags in SO. Also, writing manuals is part of programming...sorry I could not find user-manuals-overflow.com. This was the first time I got a queston to get upvoted so many times and so many views quickly. thanks for breaking the flow of it :S To all others thanks! – Keenan

Seems fans of the second person can make second person phrases look better than the equivalent third person phrase and vice versa. – Keenan

This question appears to be off-topic because it is about writing style – Murrhine

This question appears to be off-topic because it is about style guides for documentation and not programming – Nephritic

Answer 1

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).

Dib

it's quite possible - though unusual - for good scientific papers to use the definite second person. I think it's old fashioned and painful to avoid it just 'as a rule'. – Fortitude

Answer 2

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.

Component

Answer 3

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.)

Lust

How about "Click the button. Type your name in the dialog box." – Divider

I feel like you're kind of doing apple to big apple here... I would personally think something like "Clicking the button will show a dialog box where the user can enter his or her name" is a more faithful translation from the first form to the second. Your point is still valid and reasonable, though, even if your second example does feel unfairly exaggerated to me when I read it. :-) – Carlenacarlene

@Gilbert Le Blanc: I agree that that's crisper, but it can be confusing for some users who don't realise the connection between clicking the button and the appearance of the dialog ("I can see the button, but I can't see the dialog box"). So it depends on the audience :-) @Platinum Azure: You're right of course - though I wasn't really attempting a fair translation, so much as imitating the styles of different technical literature I have come across... – Lust

-1. Your post offends people that can't see. – Herewith

An alternative that's succinct but avoids first person: "Click the button. A name can be typed in the dialog box." – Kayak

@ozmo: I think you mean "second person" (first person is "I"). And "click the button" is second person (even if the "you" is implicit). – Lust

Answer 4

• 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.

Hautevienne

Answer 5

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?

Divider

Answer 6

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.

Barbellate

Answer 7

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.

Bouillon

Answer 8

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".

Ipomoea

Answer 9

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?

Fluker

Completely unrelated, but I really love the user name. :-) – Carlenacarlene

I certainly can't claim that what you say isn't a dogma of trade writing, but when thinking about it in this context, the very idea of dropping readability at the expense of "image" is pretty silly. Indeed, it begins to fall into the category of "because that's how we've always done it" which can be an excellent or lousy answer, depending... – Hbomb

Answer 10

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.

Dugong

Answer 11

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'.

Individually

Answer 12

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.

Ginnygino