Re: The 'user' in User Manual

Subject: Re: The 'user' in User Manual
From: "D. Michael McIntyre" <michael -dot- mcintyre -at- rosegardenmusic -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Sat, 3 Feb 2007 02:07:03 -0500

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 &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.


References:
RE: The 'user' in User Manual: From: Lauren

Previous by Author: RE: Agile, SCRUM and Technial Writing
Next by Author: Re: The 'user' in User Manual
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