TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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?
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 & 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 & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as lt34 -at- csus -dot- edu -dot-
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 & 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 & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as scavanaugh -at- nat-seattle -dot- com -dot-
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 & 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 & Manual: http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
