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

Subject: When they shouldn't be experimenting (was RE: Encouraging learnin g by experimentation?
From: KMcLauchlan -at- chrysalis-its -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 5 Dec 2002 14:23:30 -0500

> -----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,

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

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

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?


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.

Previous by Author: RE: Unionizing?
Next by Author: RE: Description of Tech Writers
Previous by Thread: OT: Dan, Tech Pubs managers, SNAGIT, etc.
Next by Thread: RE: techwr-l digest: December 04, 2002

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

Sponsored Ads