When they shouldn't be experimenting (was RE: Encouraging learnin g by experimentation?

[KMcLauchlan -at- chrysalis-its -dot- com]

> -----Original Message-----
> From: Hart, Geoff [mailto:Geoff-H -at- MTL -dot- FERIC -dot- CA]
> Sent: Thursday, December 05, 2002 1:14 PM
[...]

The design
> problem then becomes how to separate out contextual 
> information (why you're
> doing what you're doing, what you need to know before you can 
> try to do it,
> and how the doing could go wrong) from procedural information 
> (forget all
> that context and just give me the steps I need to follow). 
> That's probably
> the simplest way to adopt the Hackos approach.

I'm in a constant, running battle to streamline my 
setup docs for people who "just want to get on with it".

If I leave out the "clutter" like "what to consider before 
you invoke this config command", or "Caution! This command 
zeroizes the HSM -- all data and cryptographic objects will 
be lost!"... then I get reasonable-sounding complaints 
that we must tell the users the information that they 
need in order to make decisions... and to keep themselves 
out of trouble... and away from the Customer Support line.

Never mind that the interface provides most of the same 
warnings and requires acknowledgement before you can 
proceed into a destructive sequence, "it has to be 
documented for Common Criteria compliance" or "the engineer 
at the Beta customer says he wants the setup guide to 
be more 'thorough'..." or somesuch.

If I put in the "you need to know this" info, between the 
steps, I get complaints that:  "It's hard to follow. The 
flow is interrupted. I want it all on one page..."

If I make a table of all the setup/config commands in 
the order that they will be encountered, and with the 
minimal syntax (required arguments and params) -- which 
DOES just fit onto one page (sorta... with small type...) 
then "it needs an example for each command" and "you 
absolutely have to show the options for each command 
that must be modified if you set up *with* DNS, 
versus *without* DNS."

In reality, I generally start with an overview chapter 
that gives a point-form list of the general steps you 
will perform (in the form of cross-refs to the 
relevant section headings, later in the book), and then 
I start each chapter with a very brief, point-form 
"So far, you have:
  - done this and,
  - done that.

 In this chapter you will:
  - configure frammis
  - stop frammis services
  - restart frammis so that the new settings can take effect."

And then I proceed with the command sequences 
to get through whatever that chapter is about, 
with:

"command <-sub-cmd> <-param1> <-param2> ...

  Example
 thiscommand -thatsubcmd param-we-used-in-the-lab other-param-we-used

Warning(little bomb icon) -- blah, blah, blah
Caution(yield icon) -- blah, blah, blah
Note(little notepad icon) -- blah, blah, blah"

And, of course, some people demand to have the 
warnings before the command (for obvious reasons), 
while other people demand that the sequence be 
always the same, and the warning/caution/note stuff 
should always come after the standardized 
command-syntax-followed-by-command-sample.

There's more, but you get the idea.  

I have gone so far as to produce two of the same 
document, one version to satisfy one crew, and 
the other for the other crew.  Aside from some 
lifted brows and the gimlet eye and "you wasted 
time doing it twice when the deadline was so 
tight?", I got "Oh no... we can't add yet-another 
item to the BoM and to stuff into each product 
box! Besides, you just doubled the PV testing 
workload! Pick one and go with it!"

(They don't actually shout, but you can hear 
the exclamation marks.....  :-)

When possible, I herd them into a room and let 
them fight it out, and simply present me with 
the consensus that they've achieved via democratic 
or military means.  But, it's not always possible.
I think they're catching onto my tactics.

So, for the moment, they've settled on "command 
first, notes-and-warnings after".

How do the rest of y'all deal with that 
particular dilemma?

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check out SnagIt - The Screen Capture Standard!
Download a free 30-day trial from http://www.techsmith.com/rdr/txt/twr
Find out what all the other tech writers, including Dan, already know!

Order RoboHelp X3 in December and receive $100 mail in rebate, FREE WebHelp
Merge Module and the new RoboPDF - add powerful PDF output functionality
to RoboHelp X3. Order online today at http://www.ehelp.com/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
http://www.raycomm.com/techwhirl/ for more resources and info.