Re: The 'user' in User Manual

["D. Michael McIntyre" <michael -dot- mcintyre -at- rosegardenmusic -dot- com>]

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.