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:"Lauren" <lt34 -at- csus -dot- edu> To:"'Steve Cavanaugh'" <scavanaugh -at- nat-seattle -dot- com>, "'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 22:31:50 -0800
Steve said, "The Test Operator clicks here, the PC responds with this, the
Unit Under Test does that..."
Here's an example: For processor 1 perform the steps that follow. [steps]
Each set of steps for each processor will have the same flow and active and
neutral voice. To be quite honest, I have never found a sentence that could
not be active and neutral. I have, however, used the occasional passive
voice to improve balance and tone.
In your example, you have indicated the "test operator." Who else will
click? If there are multiple users, then you do need to indicate users in
their roles. This does not mean that the entire document is written with
reference to "user." Your example can be written as "Click here. The PC
will respond and the test unit will..."
Documents are generally, and should be, written for one user. A User Manual
is written for a user and a System Administration Manual is written for
another type of user, essentially. The two types of users may use the same
systems and each user's documentation may cover several systems and the two
users make have inter-dependencies. So a user may have the direction "Log
in after the system administrator configures the system." The system
administrator may have the direction "have the user log in..." The
important point here is to write to the audience. Addressing a third-party
within a document does not change the stance to 3rd person. The document is
still written for the primary audience.
Another way to think about keeping the document neutral, is to think about
keeping a second person out of the document altogether. When the document
is written in 2nd person (You) or any non-neutral voice, then *you*, the
author, are in the document and you should not be there. Let the document
read as though it is coming from the reader's own mind. So the reader can
think, "how do I do this?" and the document is the thought process the
reader would have if the reader knew what to do. Like, "Where do I click?"
"Click here." This really shortens the steps to learning something new
because the reader does not need to filter out a third-person.
I feel for you in having to parse cogency from an engineer's hen scratch,
but that really is a Technical Writer's job. I find to best to understand
the subject from the gibberish that is given to me and then write it right,
rather than re-write the gibberish.
Lauren
-----Original Message-----
From: Steve Cavanaugh [mailto:scavanaugh -at- nat-seattle -dot- com]
Sent: Friday, February 02, 2007 1:10 PM
To: Lauren; Cardimon,Craig; Techwr-l
Subject: RE: The 'user' in User Manual
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-
