Re: You or he/it? (Take II)

Subject: Re: You or he/it? (Take II)
From: "Yves Barbion" <yves -dot- barbion -at- gmail -dot- com>
To: "Geoff Hart" <ghart -at- videotron -dot- ca>
Date: Wed, 21 Jun 2006 16:40:42 +0200

This is what the Microsoft Manual of Style for Technical Publications says:

Second Person

In general, use the second person *(you)* in most product documentation to
refer to the user. Using the second person focuses the discussion on the
user and makes it easier to avoid the passive voice. In material intended
for developers, use the second person for the developer and use the third
person *(the user) *for the developer's end user. Differentiate between *you
* (the developer) and the program and actions it can perform.

Do not write in the first person *(I* or *we)* except in some specific
circumstances (see First Person <idh_first_person.htm>).

*Correct*
Just because you use Windows to get your work done doesn't mean you can't
have fun too.
You can use Help topics to present information about your program in a
format that users can access easily.
You can use this function in your program to allocate memory.
Your program can call this function to allocate memory.
Now Windows is faster and easier to set up.

*Incorrect
*Just because Windows is used to get work done doesn't mean it can't be used
for fun too.
You can use Help to present information about your program in a format that
can be accessed easily.
You can call this function to allocate memory.
We've made Windows faster and easier to set up.

Avoid writing error messages in the second person; by making the user the
subject, it can sound as if the user is being blamed for the error. However,
second person is useful in text that provides a solution or asks a question.

*Correct*
The printer on LPT1 is not responding.
Try restarting your computer.
Text outside the margins may not print. Do you want to continue anyway?

*Incorrect*
You are unable to print on LPT1.
The computer should now be restarted.

*See also* Active Voice vs. Passive
Voice<idh_active_voice_vs.._passive_voice.htm>,
Error Messages <idh_error_message.htm>, First Person <idh_first_person.htm>,
should <idh_should.htm>

Best regards


--
Yves Barbion
Technical Writer
Adobe-Certified FrameMaker Instructor
____________________________________

U&I Learning nv (formerly ATeK nv)
Molenaarsstraat 111
B-9000 Gent
Belgium
Tel.: +32 9 265 74 72
Fax: +32 9 265 74 84
www.uni-learning.com
____________________________________
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
RE: fwd: you or he/it: From: Dan Goldstein
You or he/it? (Take II): From: Geoff Hart

Previous by Author: RE: Coping with sub-par contractors (was: Frustrated)
Next by Author: Re: Poll: How do you differentiate commands, etc. in text?
Previous by Thread: You or he/it? (Take II)
Next by Thread: RE: You or he/it? (Take II)


What this post helpful? Share it with friends and colleagues:


Sponsored Ads