Re: Checking assumptions at the door?

Subject: Re: Checking assumptions at the door?
From: "Lin Sims" <linda -dot- sims -at- verizon -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 4 Jun 2001 10:36:39 -0400

Oh, there's no seeming redundancy about it. There's a LOT of
redundancy and a fair bit of copy-n-paste involved. It's repetitive, but
I would rather be able to open a manual to ANY procedure and find
a roadmap telling me how to get to the point where I can use the
procedure than find it hanging out in the breeze.

I have seen manuals with procedures whose first steps were "On
the Gribnatz screen, click Felderbibble." with no idea how to get to
the Gribnatz screen. The preceeding procedure won't be about how
to get to the Gribnatz screen, either. It'll be about Doodling the
Wingnut on the Bickleboard. In other words, while I may know what
I need to do, I may not know how to get there. A manual that tells
me how to do what I need to do without telling me how to get there
first isn't very useful, especially if I have to hunt all over creation for
that little roadmap.

For similar reasons, any install guide I write has the following
table/roadmaps right up front:

1. Task Check list (high-level how-to, sort of, with boxes to check
off as you complete tasks)
2. Hardware Check list (the hardware specifications--what sort of
computer, what OS, how much RAM, how much disk space, etc.,
again with check boxes)
3. Software Check list (all the software that needs to be installed
BEFORE you can install this software--third-party stuff, patches,
what-have-you, also with check boxes).
4. Information Check list (user ids to be set up, directory paths,
environment variables, passwords, anything the installation
wizard/script could ask for while installing--IN THE ORDER THE
INFORMATION IS REQUESTED--with empty boxes to write the
information in prior to installing).

I've gotten lots of compliments from service engineers and installers
for doing this--they seem to find it terribly handy to have all of this
information in one place BEFORE they start the installation rather
than finding out they need it as it's installed.

And lord knows, if one of our customers is foolish enough to try to
install the software by themselves, there's at least an even chance
they'll succeed.

On 4 Jun 2001, at 9:15, Hart, Geoff wrote:

> <<One of the things I dislike about a lot of the manuals I've seen is
> that too many of the procedures assume that the user has a particular
> piece of knowledge or has already done some other task. In my manuals,
> I list a set of assumptions before every single procedure with
> references to where a particular piece of information can be found or
> where a required procedure can be found.>>
> Interesting choice. At first glance, this seems like an eminently
> sensible approach, despite the seeming redundancy, and second glance
> isn't revealing any obvious problems. I'll be interested to see what
> others have to say about this.

Knowledge is Power.
Power Corrupts.
Study Hard. Be Evil.


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Cub Lea, specialist in low-cost outsourced development
and documentation. Overload and time-sensitive jobs at exceptional
rates. Unique free gifts for all visitors to

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.

Checking assumptions at the door?: From: Hart, Geoff

Previous by Author: Checking Assumptions at the door
Next by Author: Re: What is best way to show submenus in a document?
Previous by Thread: Checking assumptions at the door?
Next by Thread: RE: Checking assumptions at the door?

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

Sponsored Ads