TechWhirl Sponsors

About TechWhirl

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.

All specifications are subject to change, but that's in the details. You
add, subtract, rethink. That's to be expected.

At the same time, every project should have specific metrical targets to
hit, because otherwise projects piddle off into the sands rather than having
a stopping place. Even ongoing projects, such as updates and improvements,
need milestones that are measurable.

I say again, with feeling...if a manual is produced without metrics for its
outcome, you do not know if you have done your job. The boss's subjective
impressions don't count. They may be important within the context of the
company you work for, but that says more about the company than about the
manual. If the standard for performance is the boss's "Hey, I like it!",
then you are not even being given the same potential for meeting standards
that's awarded to assembly workers or janitors. You're expected to produce
art, not measurable communication.

There's no reason why a manual can't have measurable performance metrics. A
simple test might be "During usability testing, users must be able to locate
applicable assistance for unfamiliar tasks within X seconds". Write such
metrics to factor out the difficulty of the product. Observe only how often
a user flips from page to page, tinkers with menus, gets frustrated and
clicks out of the help file before completing the task. Set actual targets
of seconds elapsed or pages flipped.

In the absence of testing, you have to rely on heuristics. If that's the
case, then in my view you're obligated to have the very best heuristics,
which come to us courtesy of research and reading. This isn't ruining the
profession, as some have said on this forum; it's enhancing it.

If a writer has flimsy heuristics and no testing, then how do she know she's
doing anything right? Because users don't go on rampages, thirsting for her
blood? Users are all too familiar with documentation that's more suitable
for lighting fires than for reading. They're tragically used to it, so much
so that really good doc excites them. We'll know we've become a great
profession when fabulous doc is so common that substandard doc cause a howl
of outrage.

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
Check our Web site for the upcoming Clustar class infohttp://www.simplywritten.com

> I have never produced a manual that conformed to what I was asked to
> produce at the start of the project. Now, some may consider that to be
> just cause for banishment but in every case, the person who asked me to
> produce the manual didn't really know what was needed. It takes a lot of
> blood, sweat and tears as well as the occasional discreet application of
> the Official Technical Writer's 2x4(TM) to convince the powers that be
> what a real manual should and shouldn't contain.