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: An Engineer has infected my young mind! From:"Mason, Catheryn" <CMason -at- INFINITEC-COM -dot- com> To:TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 18 May 2000 14:53:25 -0500
Sierra:
You sound as if you know who your audience is and what they need. My first
piece of advice would be to find like-minded allies, perhaps field techs or
other engineers, who agree with your approach. If you poll other folks in
your organization and find more support, you won't have a hard time getting
this guy to back down. He might be a technical expert about the product but
he's not a user documentation specialist; that's your job. The question is
how to let him know that in a way that will not burn bridges.
I agree with your approach to the documentation set. For many systems and
pieces of equipment, one large manual is just too unwieldy. And no one but
system experts and fellow engineers wants to read a manual through even
once, not to mention two or three times. Users, in general, just don't have
the time for that (even if they had the interest).
You say that your product is "complex and difficult to understand" and you
rightly point out that your job is to make it easier for your user to
navigate. Hammer out the pros and cons, if you must, of your doc plans as
opposed to the engineer's. Enlist the support of folks that work in customer
service and field support. Gather support from those of us on this list, or
from books/articles/user studies. Just don't allow yourself to be forced
into writing a document that you know is sure to have usability problems. If
you were hired to do a job, you have to be allowed to do it and to exercise
your own judgment. Look at other (good and bad) manual sets for comparison.
We sell telecommunications equipment, and our system is shipped with three
manuals -- one is for installation, turn up, maintenance, and test on the
hardware; one is for operation of the software; and one is a system manual
that offers all technical specs, etc., that a customer might want or need to
know, at least on occasion, but that is not necessary to install or operate
the equipment.
Slogging through tons of material that is not relevant to the task at hand,
especially when you are trying to install something or perform a certain
task, is incredibly frustrating. Make your case, get folks on your side if
necessary, and proceed with your plan. As a lone writer in particular, you
*have* to be allowed to exercise your own judgment in designing the product
documents. You can let it be known that you appreciate and value everyone's
input, but the decision is, and should be, your own.
Good luck.
Catheryn Mason, Technical Writer
Infinitec Networks
cmason -at- infinitec-com -dot- com
Winner, 1999 IABC Bronze Quill Award of Excellence for Technical Writing
2000 IABC Merit Award for Technical Writing
