You and Your - how to stop technical authors using these!

[LTinker68]

I'm not at all sure it should be implemented.

That's why I said there should be an option to disable the feature.

Although the idea of running it as a report is a good one, too. That way the feature is always there if you want to use it, but it doesn't interrupt you as you work, and if you're not interested in the feature, then you just don't run the report.

And it should be a feature directly in Flare, and not in the full Analyzer.

[whunter]

At a previous company we used some software that did this. I thought it was called Acrocheck but it appears to be called Acrolinx now. Anyway, you could basically input your style guide into it (among other things) and then run it like a spell checker, and it would show you all the places where you deviated from the style guide. I think you could also configure it to enforce the rules (meaning, you couldn't save something if you broke a rule), but we didn't do that.

I think this particular software is for huge multnational corporations with large writing teams (and priced accordingly), but maybe there is something else out there that is less robust that smaller teams could use?

[gmel999]

Pls. excuse a late comment....
Great discussion here, and I agree with Nita -- IMHO, there is nothing wrong with using "you" and "your" appropriately in user documentation. After all, you want to speak to the user, don't you? I think it gives a friendlier aura to the doc. Some of this may be personal choice, and some may be cultural, perhaps? I can't tell you how much of that "The user does this, the user does that...." I had to get out of our process documentation.

Ramon -- I agree with you, too. This kind of thing should be in a style guide, and the manager or supervisor needs to (somehow) enforce what's there.

Mel
(Member of RFUG - the Rochester [NY] Flare User Group)

[RamonS]

If you have many "The user does this..." things then maybe a list is the better way to go:
1. Do this...
2. Do that...
3. Don't do this

Also, passive voice or...uh, grammar terminology missing, see example...circumvents the entire issue AND is more accurate as it describes what will happen when something is done to the controls on the screen. As in "After clicking Print Print Properties appears...." with "Print" being a button caption and "Print Properties" being a form title.
"You" and "Your" speaks to the user, but it is rather casual. The reception of this may well be culturally influenced. If I read this in the documentation of a serious business application I'd be taken back by it, if not offended. This buddy tone would just rub me the wrong way and I'd suspect lack of professionalism. I'm a customer and I want respect. I think that just may be my German heritage where "Du " and "Sie" are different things, but in English it is all "you". The command style of lists is the exact opposite, but it is typically shorter, comes with an orientation, allows for detail, and gets the user the results.

[crdmerge]

If you're going with "the user," you'd better go with "the users," to stay out of that his/her gender morass ("their" is so much safer, don't you think?).


Leon

[Nita Beck]

As in "After clicking Print Print Properties appears...."

So are you saying this is a correct construction or an incorrect construction? In my book, this construction is grammatically incorrect, in that the Print Properties (window) isn't capable of clicking anything. "After clicking Print" is "dangling." I'm not being nit-picky, but sincerely can't tell if you think this is correct or incorrect.

(My "schoolmarmishness" is showing. Taught high school English for four years. Taught college-level technical writing for 18...)

[ChoccieMuffin]

What an interesting discussion! I had one job where I was banned from using active voice, and was not allowed to use the word "you". However, when issuing instructions the second person is used (see what I did there?) so it is not possible to avoid the second person completely. (Fortunately the bloke who was reviewing my work didn't actually realise that an imperative was addressing the same person as a piece of information that includes the word "you", and that thought made me smile and kept me more or less sane. ;-D )

Needless to say, I didn't keep any examples of that piece of work for my portfolio as although it was what was required, the style was clumsy, inelegant and in places extremely stilted.

[nickatwork]

Very interestuing reading through this....of course you need to write based on a (corporate) style guide that is defined, and things like this should be specified if people take issue with its use.

Personally, I dont mind the use of 'you' and 'your'. I write instructional documentation for users, I have met these users, they are just like me, doing a job, need a result, and need the information presented in a straight forward manner. Most of them wouldn't even notice if we are using 'you' or 'your'. I find that most times the ones that do are people who have been in the writing business at some point. As long as the message is clear and to the point, people are generally happy. How many times have you picked up a guide for a cellphone or your tv and analysed how it is written, rather than just read to get the information that you need? Most users do the same thing, they read because they have to, because they don't know something and your document has the answer. They care more about the answer than the way it is delivered, they only start analyzing the delivery if the answer is unclear or difficult to find.

I find it always worth while to take a step back, look at the bigger picture of whats being produced, and meeting the users need, because after all thats who we are writing for.

Of course I wouldnt be using you/your in a business directed document that ends up going to directors or people like that. Its all about the audience.

[RamonS]

As in "After clicking Print Print Properties appears...."

So are you saying this is a correct construction or an incorrect construction? In my book, this construction is grammatically incorrect, in that the Print Properties (window) isn't capable of clicking anything. "After clicking Print" is "dangling." I'm not being nit-picky, but sincerely can't tell if you think this is correct or incorrect.

(My "schoolmarmishness" is showing. Taught high school English for four years. Taught college-level technical writing for 18...)

That is how I'd write it. Print Properties isn't clicking anything, but Print (the button) is clicked. Could also write "After Print is clicked Print Properties appears."
See, English is my second language and if my first example would be written in German, then a comma would be after "Print" (After clicking Print, Print Properties appears.). English has (to me) a very awkward use of commata that in most ways do not support reading or understanding, because commata are to be omitted in most places where they'd make sense. That sometimes makes me omit commata where they need to go. And then there are regional differences, best example is the comma before "and" in a series. I tend to use it as this is how I learned it in school, but omitting it is not wrong (depends on who you ask).
Using "you" and not using font styles to indicate screen components the whole sentence would be sth like this: "After you clicked on the Print button the Print Properties dialog appears." That is much longer and less accurate as it may not be me clicking that button, but my buddy who shows me how to do it while pointing out the help. I know this is splitting hairs and entirely up to personal preference.
As this discussion shows, there is no right or wrong. This is language, not math.

[Nita Beck]

Thanks for the explanation. If I were your English editor, I'd instruct you that your construction is not grammatical English, regardless of the presence or absence of a comma (which I would include, by the way). To make it grammatical, it would need to be "After Print is clicked, ..." The construction as you've written it syntactically means that the window has clicked the button, which is obviously illogical. In English grammar, this kind of faulty construction is called "dangling" (though it escapes me now whether it's a dangling modifier, a dangling participle phrase...).

(Again... I know my "schoolmarm" skirt is showing... I don't mean to nit-pick.)

[RamonS]

Thanks for pointing it out. It shows that any help or other documentation needs to be edited by a skilled language expert. Even a misspelling in the About box just makes a product look less professional.

[i-tietz]

Depends on what parts you have in the documentation. Some (bad) documentation has description of interfaces only. I have learned you are supposed to have an procedure-based part as well as a descriptive part.

In step-by-step procedures it will look very strange without having a "you" ...
Passive voice is hiding who has to do sth. Is it done by the software or the machine - based on "the settings that have been determined"?
Whenever somebody has to do sth personally, you are supposed to tell him exactly that.

A description of the GUI might be written in a different way, but even there you can say things like "If you click on this button, the window X opens."
But here I would go a different way and prefer the short info: "Opens window X." That gives the same information to the user and is a lot quicker to read. Although I know that this sentence lacks the subject ... We're not writing fiction books. The user wants to get the info sought-after and then go on with his real job.

[ccardimon]

Maybe we should be using "you" and "your" --
http://davidbarneswork.posterous.com/6- ... -for-apple

[RamonS]

Maybe we should be using "you" and "your" --
http://davidbarneswork.posterous.com/6- ... -for-apple

"Your app" instead of "an app"? Given Apple's EULAs the customer does not buy an app, they obtain the unilaterally revocable right to use it. So if anything at all, it would need to be "an app that Apple deemed you worthy enough to use". Now that would be accurate!

I think it comes down to personal preference and as mentioned before the audience. Apple is courting the hip and rich young uns, so maybe the buddy tone hits the mark for them.

[ccardimon]

Apple is courting the hip and rich young uns...

Sadly, I am neither hip, young, nor rich.

[RamonS]

Neither am I. And because I do not have an iPhone I do not have an iPhone. But apparently I watch too much TV....

[ccardimon]

I do not have an iPhone. But apparently I watch too much TV....

I have a Droid X and I also watch too much TV. If you do have a smartphone, what kind do you have, if I may inquire?

[Andrew]

I think it comes down to personal preference and as mentioned before the audience. Apple is courting the hip and rich young uns, so maybe the buddy tone hits the mark for them.

It's not purely personal preference; there is a valid reason to choose one over the other: tone. If you are writing instructions for operating a nuclear power plant, or for something in an industry which is itself deadly serious, you may be very well advised to remove any 2nd person POV from your documentation. However, if you are dealing with children's toys, or whimsical devices, or software designed for use by folks with little post-secondary education, a little "you" can help you communicate more effectively by connecting better with the audience. Small degrees, but in many cases, worthwhile.

[RamonS]

That is why I wrote "...and as mentioned before the audience."

[Andrew]

That is why I wrote "...and as mentioned before the audience."

Hm. It would help if I read more carefully.

[i-tietz]

If you are writing instructions for operating a nuclear power plant, or for something in an industry which is itself deadly serious, you may be very well advised to remove any 2nd person POV from your documentation. However, if you are dealing with children's toys, or whimsical devices, or software designed for use by folks with little post-secondary education, a little "you" can help you communicate more effectively by connecting better with the audience. Small degrees, but in many cases, worthwhile.

????
You gotta be joking ...
The barely literate people can live with "you", but the academics don't? What antique way of looking at people is that? We are'nt writing marketing texts but manuals!
Or are you trying to tell me that with nuclear power stations it is'nt necessary to make clear what the engineer has to do himself and what the machine does all by itself? Or are you trying to imply that if the engineers read a "you" they will feel relegated and won't go on reading the manual?

[RamonS]

There are many places where traditions blur things. Typical example is a bank. The tellers are expected to be dressed nicely and look businesslike. A dude with tattoos, ripped jeans, muscle shirt, bling, and flip flops is most likely as capable in banking as a greased up guy, but honestly, which one would you pick?
Same applies to documentation. Some audiences just prefer / expect the bland and dusty robotic approach. And heck yea, tech writing is marketing. The documentation is as much part of the whole product as the box it comes in is. Nevertheless, I think we agree that this discussion is about nuances. If the meat isn't there then the gravy doesn't do much.

[Andrew]

There are many places where traditions blur things. Typical example is a bank. The tellers are expected to be dressed nicely and look businesslike. A dude with tattoos, ripped jeans, muscle shirt, bling, and flip flops is most likely as capable in banking as a greased up guy, but honestly, which one would you pick?
Same applies to documentation. Some audiences just prefer / expect the bland and dusty robotic approach. And heck yea, tech writing is marketing. The documentation is as much part of the whole product as the box it comes in is. Nevertheless, I think we agree that this discussion is about nuances. If the meat isn't there then the gravy doesn't do much.

Precisely.

[i-tietz]

Goodness.
I knew the yanks are a very traditional people, but this is ... - I'm afraid even the brits I know are more innovative and open ...

[ccardimon]

That's why we Americans are Puritanical. The Brits are [insert description here]