RE: The 'user' in User Manual

Subject: RE: The 'user' in User Manual
From: "Steve Cavanaugh" <scavanaugh -at- nat-seattle -dot- com>
To: "Lauren" <lt34 -at- csus -dot- edu>, "Cardimon,Craig" <ccardimon -at- M-S-G -dot- com>, "Techwr-l" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 2 Feb 2007 13:10:29 -0800

This is a good discussion. For the simple example below, I agree this
must be the best approach. However, I often find that I'm writing a
manual that describes how a test operator interacts with a PC running a
program; a Unit Under Test running three processors, each of which is
running its own program; and perhaps some test equipment that may or may
not be running their own programs. The responsible engineer has handed
me a sentence describing a test step, and it is literally impossible to
tell who is doing what to whom! The primary reason for this is that the
sentence is loaded with passive voice. In correcting this mess, without
explicitly identifying to whom I am referring, it is very difficult to
write a cohesive sentence about the procedure that I want the user to
follow. In these cases, I tend to say "The Test Operator clicks here,
the PC responds with this, the Unit Under Test does that..." Otherwise
we tend to think we're done when we've barely started!


Steve Cavanaugh
Sr. Technical Writer
NAT Seattle Inc.

-----Original Message-----
From: techwr-l-bounces+scavanaugh=nat-seattle -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+scavanaugh=nat-seattle -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Lauren
Sent: Friday, February 02, 2007 12:52 PM
To: 'Cardimon,Craig'; 'Techwr-l'
Subject: RE: The 'user' in User Manual

OMG! I read the manual for Test Director and nearly every sentence
included the word "you." That was a most annoying read indeed. "You"
has a tendency to get a little bossy. Like "you will do what I say."
People do not like to be told what to do as though they have to do that
and "you" has that connotation. I take a neutral stance in my writing
and avoid 1st ("I"), 2nd ("you"), and 3rd ("user") person voices. Some
writers say that they have a hard time maintaining neutrality, but I was
taught 14 years ago when I studied Technical Writing in college, that
neutral is best and I maintain a neutral voice in user manuals.

How about a simple save file process as an example of the 4 stances?

1st - I click "File," "Save As," and choose a name for the file when I
want to save the file.

2nd - You need to click "File," "Save As," and choose a name for the
file when you want to save the file.

3rd - The user needs to click "File," "Save As," and choose a name for
the file when he or she wants to save the file.

Neutral - Click "File," "Save As," and choose a name for the file to
save the file.

Notice that the neutral stance uses fewer words. What ever stance you
choose, as you noticed, you should be consistent. Now this message uses
a conversational tone so there is a mix of stances, otherwise I would
say "choose and maintain a consistent stance."

Lauren


-----Original Message-----
From: techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+lt34=csus -dot- edu -at- lists -dot- techwr-l -dot- com] On Behalf Of
Cardimon,Craig
Sent: Friday, February 02, 2007 11:58 AM
To: Techwr-l
Subject: The 'user' in User Manual

Hello, folks,



When you all are working on user manuals, what viewpoint do you most
often take? Should I:



(1) Remove all occurrences of "user" and "you" from the manual, and
recast all sentences.

(2) Take a "user"-centric stance.

(3) Take a "you"-centric stance.



Whatever I do, I need to be consistent throughout. How say ye?



-- Craig

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats
or printed documentation. Features include single source authoring, team
authoring, Web-based technology, and PDF output.
http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up to
106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as lt34 -at- csus -dot- edu -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/lt34%40csus.edu


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

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats
or printed documentation. Features include single source authoring, team
authoring, Web-based technology, and PDF output.
http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up to
106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as scavanaugh -at- nat-seattle -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/scavanaugh%40nat-seat
tle.com


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

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


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
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 admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Previous by Author: RE: Creating help on a mobile device using Windows CE
Next by Author: RE: Word numbering problem
Previous by Thread: Re: The 'user' in User Manual
Next by Thread: RE: The 'user' in User Manual


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


Sponsored Ads