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:"'D. Michael McIntyre'" <michael -dot- mcintyre -at- rosegardenmusic -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Sat, 3 Feb 2007 12:13:24 -0800
All writing is centered on the audience, or reader. If you are writing
technical documentation, then your audience is a user of technology and the
document should be written as a person thinks and not as a person talking to
another person. A technical book, however, will need to take some liberties
because a book becomes a sort of companion to the reader. Like a friend
that you can carry around. So it needs to "talk" to the reader sometimes.
How much of the book is written as the reader "thinking" or as the author
"talking" depends on the skill level and nature of the reader and the
overall "voice" of the book. The "Dummies" series of books tend to talk
directly to the reader. "O'Reilly" books tend to include a lot of
neutral-voiced content. A key to test your writing is to read as the
intended reader and avoid assuming that what you take for granted will be
assumptions shared by your reader. Naturally, having someone else read your
work will provide the best help if that reader will be honest and not spare
your feelings.
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 D.
Michael McIntyre
Sent: Friday, February 02, 2007 11:07 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: The 'user' in User Manual
On Saturday 03 February 2007 1:31 am, Lauren wrote:
> I have an easier time writing without pronouns. I also have an easier
> time reading documents that do not use pronouns. I get annoyed when I see
"you"
> in documentation and even more annoyed by he and she references or
> even worse "he/she" references.
I wonder if "documentation" includes a book about a piece of software. I
realize this thread is about a user manual, but it has been interesting food
for thought.
All of my quasi professional writing has revolved around the same open
source software project, and my main claim to obscurity, um, fame is the
most highly-acclaimed work of its kind. Probably because it's the *only*
work of its kind. When I set off writing the thing, I didn't know it would
evolve into a book. I have no training in technical writing, and nothing of
English beyond whatever required minimums (I did major in foreign languages,
so ask me what "deponent" or "pluperfect subjunctive" means any time you are
having trouble falling asleep.) My only qualification was willingness,
confidence I could do it, and about 20 years of pounding out messages on one
form or another of online.
This thread prompted me to look back on my book, and consider what I had
done as a rank clueless amateur turned big league pro (if I write two of
these a week year round, I can quit my day job!) The whole thing is a mix
of persons, but mostly first and second, in a direct I your guide to you my
reader kind of relationship, with a bit of third in ways I feel are
completely appropriate (talking about other, related projects that aren't
"we.")
Part of the "I" was me describing bits of the software I had written myself,
as I am also one of the four primary developers on the project, but there
was also an element of teacher and pupil to the thing. (No training in
programming either, or teaching. Actually, I'm a truck driver by trade, and
pretty much stuck here. Ain't no jobs for teck riters or Spinish speekerz
here Cheef. Whut else am I gon do two make the howz paymint?)
Anyway, I really think this format works in this context, and I wouldn't
change a thing, even if they doubled the $0.32 an hour I got paid for all
the time involved in writing this. (Read: don't quit your day job stupid.
There's not much future in writing books about obscure software for an
obscure operating system.)
OTOH, all the bits I've done in the manual itself are in a mix of second
person indicative and imperative, to blend with the bulk of the thing, which
I didn't write.
Just musing out loud as much as anything else, but it's interesting to
ponder this issue. I find that the only strong opinion I hold is that the
third person "the user puts the precious in the basket" style is most
definitely creepy in a Silence of the Lambs-esque way. <shiver>
--
D. Michael McIntyre
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 archive -at- infoinfocus -dot- com -dot-
