Re: Checking assumptions at the door?

["Lin Sims" <linda -dot- sims -at- verizon -dot- net>]

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

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 http://www.devahelp.com 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 http://www.cublea.com

---
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 
http://www.raycomm.com/techwhirl/ for more resources and info.