Advice for writing a user manual/documenting business process?

Subject: Advice for writing a user manual/documenting business process?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 17 Apr 2003 13:30:58 -0400

Kelly Smith wonders: <<I have been asked to write a user manual and document
the business processes associated with receiving and tracking packages at a
pharmaceutical company.>>

You mentioned later in your post that no such document exists, so let me
recommend a nice tip when building one: See John Posada's messages (in the
archives, over the past month or so) about charting the components of
products and processes. It's a very cool idea, and seems to have worked
marvelously for John.

<<I have a list of managers and business users I can get information from,
and Ihave a project manager who is going to oversee the project and my
interaction with these people. They are all strangers to me, but they have
asked for this book, so I assume they will be willing to help.>>

Bad assumption. <g> After all, you'll be spending a fair bit of time over
the next few months disrupting their deadlines by taking them away from
their paid jobs (the ones _their_ supervisors are using to evaluate them),
often with questions that will seem really stupid to them. (After all,
_they_ already know the answers.) Recognizing that you will be seen as a
drain on their time with no obvious benefit to them, one of the first things
you should do is introduce yourself to each of these people and begin
establishing a friendly working relationship.

This will take diplomatic skills, and the approach will vary somewhat among
people! You'll undoubtedly find some saints, but some of your resource
people will start out difficult and only get worse. Start thinking of how to
deal with these people, perhaps with the aid of their managers (e.g., "Geoff
really wants you to listen to him expound theories. Do that, and you can ask
him for any favor. Stop listening, and you can forget about getting any help
from him.") In fact, it's a pretty good idea to talk to their managers to
find out whether they have any objections to your work, and want to place
any limits on what you'll be doing.

One way to start would be to explain to each person what you'll be doing,
why you need their help, and how much time you expect to take (if possible
to estimate). Then ask how you can achieve this with the least impact on
them: meetings? phone calls? e-mails? Find out how often they are willing to
be disturbed (and what times are best), then make sure not to exceed these
limits if you can avoid doing so. Showing a little consideration for their
needs usually earns some consideration for yours.

<<They want me to document the day-to-day processes that a new user would
have to go through to receive or deliver packages. The software itself is
already documented, and it tells them what they can do, but it does not tell
them when they may want to use a particular function, or why. That's my

You have two alternatives here: present what the software's designers
consider to be an ideal (or at least highly effective) workflow, or talk to
actual users to find out how they actually use the software. The first has
the advantage of requiring no contact with messy humans grappling with
hostile software in the real world; the latter has the advantage of
sometimes revealing important surprises (such as the fact that your software
is unusable). Less facetiously, there are pros and cons to each approach:
the former is far simpler but potentially less effective, whereas the latter
is much more complicated but offers more potential gains.

<<I can't devote full time to the writing (although that wouldbe way more
interesting than documenting defects!)>>

Make sure to clarify the scheduling with your manager. Extra tasks like this
tend to take on a life of their own and overwhelm the poor writer who's
desperately trying to keep up with her regular job. (That's you!) Figure out
a mutually satisfactory balance between the requirements of your two jobs,
then constantly re-evaluate that balance over the next several weeks to be
sure that both of you will remain happy with it. Readjust as necessary.

<<Right now I am at the stage of figuring out exactly what they want and
need, and trying to put together an estimate for the Project Manager so that
she canwrite the statement of work.>>

Make sure to write up that needs requirement clearly and objectively.
"Document business processes" is neither. "Identify every step in the
process of receiving and delivering stuff, then describe each step"
(accompanied by a preliminary list of all steps) is a step in the right

<<At this point I'm not even sure how many different user roles there are,
or how many different procedures there may be to document.>>

The existing software documentation will give you a good overview of the
possibilities, which you can then organize into something logical--and more
importantly, something that the experts can review to confirm that you
haven't missed anything.

<<The client has assured me that their internal print shop will produce the
finalbooks, so I will also have to work with them on layout and other things
that I'm not normally concerned with. We're picturing something spiral bound
with sturdy pages (maybe laminated) that will hold up to a warehouse or
mailroom environment with lots of daily use. Any other advice on the

One thing to think through carefully is whether a printed book is really the
right way to do this. It might actually be more effective to create a
"wizard" or embedded help that guides new users through the process. That's
particularly true if the warehouse or mailroom staff routinely use handheld
computers in their work, or can't ship or receive without using their
computer. In some cases, a wall poster works better than a handbook. Where a
handbook works, you may need to size it to fit in a pair of overalls, or to
be splayed out on a cluttered desktop. Carefully consider where and how it
will be used before choosing a format.

--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada

"Work is of two kinds: first, altering the position of matter at or near the
earth's surface relative to other matter; second, telling other people to do
so. The first is unpleasant and ill-paid; the second is pleasant and highly
paid."--Bertrand Russell

Purchase RoboHelp X3 in April and receive a $100 mail-in
rebate, plus FREE RoboScreenCapture and WebHelp Merge Module.
Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.


Previous by Author: When a "shim" is not a "shim"?
Next by Author: Question about rates for freelance graphic work?
Previous by Thread: Re: Advice for writing a user manual/documenting business process
Next by Thread: RE: Advice for writing a user manual/documenting business process?

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

Sponsored Ads

Sponsored Ads