Deja voodoo

Subject: Deja voodoo
From: Kevin McLauchlan <KMcLauchlan -at- chrysalis-its -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 24 Feb 2000 15:48:29 -0500

Your many and various opinions are sought.

We have a hardware/firmware/software product,
and we have a software utility that is used
to initialize and maintain the product. In my
manual, I had explained initialization steps
and requirements by reference to the utility
program. That was the command-line/console
version. Then, they wrote a (barely) GUI version.

Since I have to document both, I wrote the
procedure "from scratch" for the GUI version --
you know... to have a fresh look at it, and
maybe pick up things I'd missed or glossed over
the first time.

I liked both versions, though there was a fair
bit of difference between them. I used elements
from each one to upgrade the other, but still liked
both. I decided to leave them both in the manual.
I reason that not everybody picks up on the same
things in the same way, and giving people two
different descriptive approaches to some of the
important-decision stuff might give the curious
and dedicated a better shot at making the right

I say "curious and dedicated" because I urge the
reader to R T [entire] F M before jumping into the
procedure, so that they can make important,
far-reaching config decisions before the fat's in
the fire, so to speak. But I know that most will
just jump in and assume they'll get it right
without too much of that pesky reading... Very few
would read the other version just to see what's there.

One of my reviewers prefers that I "standardize"
on one version. She doesn't have a real preference
between 'em, but wants me to pick one and kill the
other. I can prevail if I choose, but
should I? The information in both sections is
essentially the same, but the presentation,
approach, word-choice, some selected emphasis, is
often different. It's not as good, I suppose,
as having two people explain a thing, but it's
one guy after several months of "cooling off", so
I think it's the next best thing to two points of
view... say, one-and-a-half viewpoints... :-)

Does anybody else see value in keeping such a
difference? I can't really just amalgamate,
because it would then seem annoyingly
repetitive. Are there strong arguments AGAINST?



Previous by Author: RE: Polite international e-mail
Next by Author: testing the documentation
Previous by Thread: Re: Working for a liar, one more thing
Next by Thread: RE: Deja voodoo

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

Sponsored Ads

Sponsored Ads