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

[peterbrown05]

yeah - that works pretty nicely. obv just got to watch out for them accepting the auto suggestion and inserting something like this in the text all over the place:

4. Then when you *** WARNING DON'T USE THE WORD YOU *** click the button it will cause the dialog to be displayed...

but; it does seem to work nicely providing they dont fall into this trap. thanks for the suggestion.

[RamonS]

Could intentionally put misspelled words in the warning, which should get picked up in the final spell checking.

[JudyH]

I just reviewed the documentation I've been working on (a Flare project with embedded Mimic movies). I found that, for the Flare (more formal) documentation, I have avoided second-person phrasing -- but, for the Mimic movie inserts, "you" seemed appropriate, as I am addressing the individual who is working through the interactive forms. Flare is the reference document; Mimic is my own voice as I look over the user's shoulder, in a sense. (Of course, the Mimic movies will be omitted from any hard-copy output.) I think either style can be considered correct as long as the author is consistent and is keeping in mind the audience, the medium, and the intended tone.

[Andrew]

So I don't think there's a right or wrong, just as long as you're consistent in that document (or group of documents) and it's appropriate to the audience.

I agree.

Peter, it sounds like your team could very much benefit from an editor. In a perfect world, you could hire one (or become one and hire someone to replace you). Since your world is probably not perfect, I'd suggest a temporary peer-editing (length of time depends on your schedules): edit each others' work for a period of time to get everyone on the same page. Periodically repeat that process (say, once per year) to keep it consistent and fresh.

[lensflare]

I, too, would like to know if there is a programmatic way in Flare to parse a body of text and then take action (in this case, deleting the "offending" entry). Barring that, this may be more an editorial, style guide, or word usage issue. This certainly introduces the need to monitor the content to see how well writers are adhering and complying with the defined standard. In my view, the "you" is already implied and is not needed except under special circumstances that need personalization, clearer object ownership, or to meet a specific tone.

[rob hollinger]

This is a great discussion.
How would something like this be implemented?

[LTinker68]

I would think there would be two parts to it. The first is to enable or disable the option (not every company would want to use the feature, especially if there's only one author).

For the second part, how about this... If an author types "you" or "your" or "you're", then a warning popup appears with a couple of options. One option is something along the lines of "Correct the problem", another option is something like "I choose to leave it as written". If the latter is selected, then perhaps an annotation could be added to the topic with the author's name or initials so others can question the author later. The words to prompt the warning (you, your, you're) should be configurable -- basically just a list that the team populates with watch words.

What do you guys think of that suggestion? I don't see how a straight exchange of terms would work, since you sometimes have to reword the sentence to get around using you/your/you're, so a straight swap wouldn't work. (IMO)

[peterbrown05]

that sounds ok. I would add too that during the build step (or perhaps during the analysis steps) that these watch words are flagged up as errors/warnings to aid easy check/fix.
p

[ccardimon]

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

[Andrew]

This is a great discussion.
How would something like this be implemented?

I'd probably say it would work best as a report, ideally with some kind of options to fix instances automatically (sort of like auto-correction). The report should do more than list the topic it's in, however. What we as author-editors really need is the context surrounding the usage, and the ability to edit the text right there at the point of discovery.

It's an interesting idea -- have the tool help enforce style guidelines. Perhaps give us the ability to define language patterns and rules, and then search for them. For example, we have a whole host of diction and spelling guidelines in our style guide -- always hyphenate "non-stock"; use the words click or press, never hit; use merely "click" and never "click on"; etc.

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