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.
I too would be interested in any resource
material on this question. All that I've
found seems to refer to software development.
Anecdotally...
I am a lone technical writer. I would not
willingly kick any of my docs out the door
without having SOMEONE -- other than myself --
go through them first.
Like other design and pre-production tasks,
technical writing is a creative and technical
process that is subject to many of the same
dynamics and pitfalls that beset software
design/writing, but without the built-in
safeguards. That is, a software writer eventually
arrives at the point where s/he must compile
and run the code. If it breaks at that point,
well they've just learned a lot, right there.
We don't even have that kind of "mechanical"
validity check. Through any combination of
honest error, misinformation/misunderstanding,
sloppiness, fatigue (in any of several senses),
or just plain, ornery Murphy-ness, our lovely
docs can be badly broken, while looking quite
nice thankyewverymuch.
Even when new software passes such basic tests
as syntax checking, compilation and running,
no self-respecting company lets it out the door
without having it verified against the specs and
then formally tested on anticipated platforms, and
in anticipated situations (i.e., on what platforms,
and in what situations are we willing to support
this beast, after we sell it? What do you mean it
hangs the system if it's asked to run more than ten
simultaneous threads?? Our customers need 100!).
The same applies to instructional text. It has to
be tested by people using it in realistic situations,
to see if you ____ any steps out, mistyped a name,
bolluxed a file/directory spec, left out or transposed
one of 9 arguments/switches on a command line,
neglected to note that the OTHER systems want the
hardware to be installed and ready before the software
is installed, but Win2K wants the software and drivers
to be ready and waiting when it "Finds New Hardware"...
I know I'm not alone in saying this --
1) Nothing I produce is perfect (dammit).
2) There are only two things that are guaranteed to
highlight the errors and omissions:
a) the passage of signifcant time, before I
do my own review or (and that time is never
available as deadlines loom),
b) somebody else doing the review.
In fact, the very fact that somebody else even
picks up a copy of my document, somewhere else
in the world, is enough to guarantee that the
veil will be lifted and suddenly *I* will be
able to see [some of] the mistakes that eluded
my own bleeding eyeballs up 'til just that moment.
(I'm considering doing a paper on that... I can
make a case for it being a quantum effect...)
Only Vulcans are able to view their own work
with total dispassion and objectivity, and it
is my understanding that very few techwriters
are Vulcan... the percentage is even smaller
among software designers... but a suspiciously
large number of hardware designers seem to have
pointy ears... but I digress.
Anyway, the most elementary considerations of
product quality DEMAND that one's work be
reviewed and tested before it is released.
If you are working for a company that doesn't
recognize and apply that principle to software
and hardware design... leave now.
If they DO apply proper review and validation
to software and hardware, then make the point
that your work is as much a product of the
company as that other stuff, and will leave at
least as bad a taste in a customer's mouth if
it is defective... and that, wonderful as you are,
you simply can't catch every glitch in your own
work.
Someday, I dream of having an editor. Meantime,
I'll make do with reviews by product managers.
But always, always, I have my work reviewed by
the Product Verification team. It's mandatory,
and not just because I say so.
Be validated, my son. :-)
/kevin
>-----Original Message-----
>From: Spreadbury, David C. [mailto:David -dot- Spreadbury -at- marconi -dot- com]
[snip]
>I have searched the Web for articles on validating
>documentation and have
>come up somewhat dry. Several places/articles mentioned that
>it should be
>included in the doc plan, which would be incorporated into the
>project plan,
>but nothing as to the "Why". Common sense and experience has
>taught me that
>it is a requirement, but the boss wants something, probably to
>'prove' to
>her boss, that it should be considered as a requirement.
*** 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
TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.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.
