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

[peterbrown05]

hello,
what is the best way at getting technical authors to stop using "you" and "your" in the documentation?
I can't see anyway to "remove" the words from the standard dictionary (thus being highlighted as an error) and using an auto suggestion doesnt really enforce it.

Any suggestions?

cheers

peteB

[lacastle]

I think the only way to stop this is to tell your writers and/or edit their work, since this is a personal preference.

[peterbrown05]

it's an in-house style rather than personal preference in this case.
just wondered if there was any way to help aid / enforce writing styles...

[RamonS]

Create a style guide that helps the writers to write as expected and QA to test the documentation. I, too, do not like the "you" and "your" usage, but since passive voice is considered bad for reasons I can't understand writing without sounding weird gets tricky, but it is possible. I always cringe when someone asks me "May I have your ZIP code?" I know I am not skinny, but it is rather obnoxious to consider me that fat that it requires me to have my own ZIP code. There are many other cases where colloquial wording introduces inaccuracies.
Then again, speaking directly to the reader may sound less abstract and set a different tone. In the end it is a matter of preference.

[Nita Beck]

Seriously, I'm curious, why do you want to banish "you" and "your" from your documentation? (I say "your" documentation because I assume you want to limit the use of second person in your [or rather, your company's] documentation, not in all documentation, right? [And I'm only gently ribbing you, not trying to be snarky.]) But my question is a serious one. What's your motivation? I taught technical writing for 18 years and never came across any guidance that suggested that second person should be outright banished. Quite the opposite, in fact.

And I agree with what the other posters have suggested about having a style guide.

[RamonS]

As I tried to show with my example, using second person may insert inaccuracies and suggests an ownership, that isn't there. I recently reviewed a tech doc and one sentence was "Then enter your vehicle record" as if the record or its bits and bytes in the database file belong to anyone or that the user has any specific relationship to that record. I did mark it up as needing to change, but haven't gotten the revised document back. I would have written "Then enter the vehicle record", which is as clear. There are other issues that go beyond you/your. I work with an application that allows for entering data related to students. I always mark up wording such as "Editing the student" or even worse "Deleting the student". All that gets done is editing a student record or deleting a student record. We do not alter or erase people.
I think restricting use of you/your may help with writing more accurately what happens and it often reduces the number of words. That said, this is my preference and it may be influenced by my native language where usage of passive voice is perfectly fine and the "you" is too personal, but it can be easily replaced with a generic. In English this might be the word "one" as in "One can enter a record" versus "You can enter a record".
Neither approach is wrong and it also may depend on the target audience. There is a difference if the document is for accountants who love abstracts, stats, and numbers, or if it is for a game intended for younger kids who may feel more comfortable with a more 'buddylike' tone.

[peterbrown05]

I agree with RamonS-
here; I have found a few things;
1. The use of you and your leads to longer sentences than needed. Since we are then translating the documents into multipel languages the costs go up significantly.

2. I have also seen it promote a more "chatty" writing style which doesn't fit in our documentation.

Im not trying to banish it outright; but I was hoping for some way that the word could be highlighted or picked up in a style checker so that it could be reworded as necessary.

Another example might be (not relevant to us but could be for some) - maybe avoiding the use of other company/trademark names such as iPod inplace of MP3 player might be desired.
p

[Nita Beck]

Thanks very much for taking the time to offer your insights. I hope that Peter, too, offers some insights into what's behind his original request. (Oh, I see Peter has been posting simultaneously to my posting. Thanks!)

In thinking about some examples, I find myself wondering how I would go about avoiding forms such as "Type your login ID," especially when I want the person to enter the login ID that, yes, belongs to him or her. If second person were banished, what would I write instead? Or what about when writing about setting user preferences? I'll admit that my preferred style of writing software user documentation (not software technical documentation, but user documentation) is to use "you," so I'll write something like "Set the options to suit your preferences" or "Set the options as you prefer." Would either of those phrasings be something you'd edit out?

BTW, I completely agree with your thoughts on using the form "Delete a student record" instead of "Delete a student," although I fear I'm guilty of that one in my own work! (And, LOL, I often am writing user docs for lawyers and accountants!)

[Nita Beck]

Peter, back to your original question, I don't know of a way to police phrasings as you'd like while editing in Flare. Sorry...

[peterbrown05]

Hi Nita

As mentioned; Im not ruling it outright; but the following suggests how I might word your examples. Note that same outcome is achieved, and word count is less (saves £'s across a large document being translated);

"Set the options to suit your preferences" --> Configure as required.

or "Set the options as you prefer" --> Enter the desired preferences.

[Nita Beck]

"Set the options to suit your preferences" --> Configure as required.

or "Set the options as you prefer" --> Enter the desired preferences.

Then, yes, truly a personal (as in, authorial) preference. I find your suggested edits quite dry. I prefer a more conversational tone, although I agree that the overuse of said tone leads to unnecessary "chattiness" (not to mention potentially higher translation costs). The aforementioned lawyers and accountants I write for are strictly within the U.S. and I haven't had to worry about translation issues.

[RamonS]

The drier approach makes sentences shorter. Keep in mind that this might be part of step-by-step instructions where skimming the list is about all the reader will do. Or to word it harshly, it is technical documentation, not a novel.

[LTinker68]

Whichever way you go, it should be consistent, so your whole team needs to have a meeting to decide which tone to use, and the tone can be different from document to document (although if you're releasing a group of documents I'd be consistent across them all). Just because it's a technical document or how-to document doesn't mean it can't be conversational or less "dry". Look at the whole for Dummies line of books (Cooking for Dummies, HTML for Dummies, etc.). I actually like those books from a reader standpoint regarding relaxed wording and such, and I find it is hard sometimes to not slide into that more conversational speech in my docs. A lot of it does depend on the audience. For instance, a set of how-to instructions for your customer might use you and your, but a troubleshooting guide or knowledgebase for support staff wouldn't have the you and your, as that documentation provides instructions they pass on to another party, not perform themselves.

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.

[rob hollinger]

Set up an auto-suggestion file with the rules you want to enforce.
Add a Auto-suggestion file to the advanced folder in project organizer.
Open it and add the word "you". Then follow it up with the rules. Each time an author writes "you", the popup window comes up. You don't have to use its suggestion, it could just be used as a reminder.
Just a thought.

[Nita Beck]

Set up an auto-suggestion file with the rules you want to enforce.
Add a Auto-suggestion file to the advanced folder in project organizer.
Open it and add the word "you". Then follow it up with the rules. Each time an author writes "you", the popup window comes up. You don't have to use its suggestion, it could just be used as a reminder.
Just a thought.

Well, that's cool. Sort of like a mild electric shock to help one break a bad habit!

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