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.
Subject:Re: The Real Offense From:"Tim Altom" <taltom -at- simplywritten -dot- com> To:"TechDoc List" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Fri, 10 Mar 2000 14:35:54 -0500
I find myself in agreement with Andrew that writers in an industry should
bother to become familiar with the terminology and practices in that
industry. A software writer who can't tell a variable from a varsity
cheerleader is, at best, a half-baked worker.
But I'm not as scathing as he is about learning and applying the vast
amounts of information that we've accumulated in hundreds of years of
publishing in lots of different environments and formats. He uses the
example of a roofer who expounds endlessly on roofing but never pounds a
nail. In my experience in both the trades and in our pseudo-profession, I've
always found that even the easiest-looking jobs invariably had levels of
professionalism. There are roofers who are essentially handymen, and there
are roofers who have completed apprenticeships, and who can accurately
select the proper materials and calculate loads on roofs.
Find an outstandingly good practitioner, and you'll find a wealth of
experience and technical knowledge. He may not be the fastest, but his work
will likely last longer. Yet there are ignorant building owners who will
hire the handyman because "anybody can drive nails into shingles, for God's
sake". Any attempt by a true master of the craft to persuade the owner of
his folly will probably result in the conclusion that the master is merely a
lazy, theory-bound fool who isn't willing to admit that his job is easy. And
if the building in question is no more complex than a doghouse, perhaps it
is that easy.
Applying good theory isn't necessarily like drag on an aircraft. It can also
function as lift. And applying good theory is vital if the final product is
to be given the ultimate proof of usability testing. Most of the
"bang-it-out" manuals I've seen weren't given any kind of testing. My
suspicion is that they'd flunk horribly. Even good, thoughtfully-built
manuals need revision after testing. Hasty manuals may need complete
I know that Andrew is right about many companies prizing page counts over
design, but I question that priority structure. I think that if many of
these companies could see test results, they'd quickly take on the look of
shock I've seen more than once as their smug assumptions fall to pieces. But
of course, if quality (defined as usability) is far down the list of "things
to ensure today", even testing won't influence their attitudes.
I personally believe that applying generally accepted theoretical
heuristics, rather than just one or two writers' personal experiences and
opinions, can drastically improve the manual's chances for a good usability
test. I'd find it interesting at some conference or another to bring in
manuals from both camps and subject them to usability study on the site, in
real time. Numbers aren't everything, but they're infinitely preferable to
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
Check our Web site for the upcoming Clustar class info http://www.simplywritten.com
> I admit that I am a harsh critic of the theory-crap that a lot of writers
> also admit to over-generalizing many writers as deliberately trying to do
> However, I feel this is a fundamental flaw in the entire tech writing
> profession. One that is dramatically hurting the profession in ways most
> do not ever address.