TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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?