Re: FWD: How does one write a user's guide without users?(LONG)

Subject: Re: FWD: How does one write a user's guide without users?(LONG)
From: Dan Brinegar <vr2link -at- vr2link -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 1 Mar 2000 19:09:38 -0700

While the following may have a certain facetious tone to it, it's actually
(it's so GOOD to be working again: I feel once-again entitled to comment on
things 8-)

At 4:29 PM -0700 3/1/00, anonfwd -at- raycomm -dot- com wrote:
>I have written a rough draft of a user's guide for small start-up company
>that I work for which was "supposed to be" using the software internally.

Question One to ask yourself and the Cosmos: What were they supposed to be
using it for? You need to know this, 'cos you've got to figure it out and
report on it for others.

>.... The software is now being targeted to an outside audience, though I
>have no
>idea who the intended is to be.

You may assume from this that the audience is/are going to be the poor
slob(s) who get saddled with it: nobody else, just them... whoever they

You may further assume they will get no training on it, have to file a
requisition for the manual, and find out about a week before their first
milestone that the computers they have been given to do the task just
aren't hoopy enough to pull it off, [they may also be told by
those-with-pointy-hair that there isn't time to write down whatever they've
figured out about the software: so you get to do that first (hang on, this
gets better!)]

>How does on write a user's guide without
>users? Any advice, comments, suggestions?

Become the User... you're a techwhirler: first and foremost a
user-advocate. You are the ideal surrogate for the eventual end-users.

Use your rough draft and whatever information you can glean about
whatever-it-is the s/w is supposed to do, and document what you go through
to try and make it to do that. Assume the worst... or even live through it
as the ultimate naieve user 8-)

Users are pretty-much *never* experts on new software. Oftentimes, they may
not even have the faintest clue about the subject-matter-domain the
software is supposed to help with. They're almost always the poor beggars
who have to go out in the rain and fix the darn thing, tho.

Play with it, break it, report on it: WWWWHW (that is, in fact, my specialty).

Task-oriented documentation written by someone in the same boat as the
user... think up some tasks, do them, include all the warnings and cautions
and notes you needed to remind yourself from one session to the next what
you had to do to wrestle it to the ground... siddown and write it all up.

Make it pretty, get a copy for your portfolio, polish your resume, and sell
yourself as one of the few techwriters around who can do what you just did:
put that in your objective block and cover letter for the upcoming job-hunt.

Of course that *may* be what the start-up *wanted* you to do: maybe after
the previous management team fired me for "just playing with the software
and bothering/interrogating the programmers" they went and hired two
rhetoricians in a row for half the price/twice as long and lost a couple of
customers who couldn't use the software; now they've learned that they do
need someone who can be the user.... break the software before the paying
customers have to: when you're not Microsoft, you can't make the customers
pay for your beta testing.

Be the user.

Heck, you may end up doing such a good job of it that they'll *always* ask
for you when they need an impossible job like this done... You'll be able
to reproduce that technique when other outfits need somebody to come in and
rescue a project: you might even become, *gasp*, an Expert on the
software. You might even follow some entrepreneur around from start-up to
start-up and always be the first person they think of when they need
something done -- I'm proof that it can happen: I went from Crippled Fat
Guy to Fat Guy with Three Contracts in just two months, because I have a
track record of being the guy to go to for this sorta thing... and I was
broke, unempIoyed and starting to get my back fixed right when Eric and Deb
(and then my other favourite former bosses) went looking for somebody --
can't grouse about any of that (but that may be another thread ;-).

This is a variant of the "Now you know how our USERs feel" fallacy

Older Gent gets on the bus this afternoon and asks the driver "Does this
one go south?"

Person one seat ahead of me starts laughing derisively, tells the guy "we
*are* going south."

/me thinks the person ahead of me *must* be a programmer.

* Older Gent is obviously visually impaired and therefore may not be able
to see the route number and destination on the side of the bus: I'm only
39 and *I* can't see the friggin thing till the bus stops in front of me
* Older Gent is probably a snowbird, and therefore cannot be expected to
know his way around Phoenix
* Older Gent could very likely have previously gotten on the bus that went
south for one block, turned west into the mall, sat there for 30 minutes
then left the mall and gone north to drop him off right where he started
before it proceeded east to the other side of the Valley
* Older Gent likely helped _Save the World_ 50 years ago, and under no
circumstances deserves getting dissed for asking an innocent and necessary
* Person Ahead of Me assumes that everyone should know exactly the same
things he/she does, and those who don't must have some defect worthy of
*Person Ahead of Me probably *never* asks for directions, and blames
passengers for getting them lost

[Oh Dear, I'm probably making unwarranted assumptions about the person
ahead of me]

In some cases, being sentenced to doing techsupport and driving in LA for
thirty days can have a curative effect on such attitudes: extreme cases may
require Rush Hour in Tokyo, Rio, or London.


Dan Brinegar Information Developer/Research Droid

The trouble with instant gratification is that it's over
so darn quick.

vr2link -at- vr2link -dot- com CCDB Vr2Link Performance S u p p o r t Svcs.

And "Mixed Company" action-scale models coming soon

Previous by Author: Re: Identifying the Figure Source in documentation
Next by Author: Re: FrameMaker - Hours to Learn?
Previous by Thread: RE: Sun style guide
Next by Thread: Re: FWD: How does one write a user's guide without users?(LONG)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads