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.
Jason Willebeek-LeMair wrote:
1. Do you need to be an electrical engineer to tell someone how to use
their VCR?
2. Do you need to be an expert in networking protocols and programming to
explain to users how to use their e-mail programs?
Max Wyss replied:
1. Yes, when all you get is a wiring diagram and a dump of the ROM.
2. Yes, when all you get is source code.
-----
If someone asks you to write instructions for a VCR and all you get is a
wiring diagram and a dump of the ROM, you should explain to that person that
you cannot do the job properly unless you get more information. Maybe
somebody can find the Eject button by studying the diagrams for a day or so,
but that is not very efficient. You must do whatever you can to contact the
product developers and ask how it works. If nobody gives you more
information, maybe, you should refuse the assignment (depending on the
circumstances). This - too - is a part of a technical writer's job.
Personally, I like the technical approach. I enjoy finding things out by
myself, rather than asking somebody else. When I write online Help I am
always tempted to go into the source code whenever I something is not
immediately clear. Sometimes that works, but asking the programmer is
usually better because:
1. It is usually faster.
2. You get extra information (for example: "That feature is designed to
prevent this or that problem" or "That feature will be replaced in our next
release")
3. It helps keeping ongoing communication.
4. You avoid the risk of misinterpreting the source code.
5. I think it is the responsability of the product specialist to provide you
with correct information. If you bypass the specialist, the mistake will be
yours.
I am not totally against reading of the design diagrams or source codes.
Technical knowledge can help. If you cannot get the right person, reading
the source codes can be faster or more reliable than asking questions. You
can use it for verification. Sometimes, it is all you've got.
The point was illustrated by a teacher of mine (Jos van Graas). He showed us
a bad example of technical writing in the form of a route description to a
local company's office. The company's name and some other details were not
legible on the photocopy we received. Our first homework assignment was to
rewrite the route description. Most of us guessed the parts that were not
legible and made beautiful maps with very clear descriptions. The next
morning he told the class that all our products were incorrect or
incomplete. When we argued he had not given us sufficient information, he
reminded us that he did tell us to call him if there were any problems.
Nobody had called him. Of course, he had pulled us a trick, but I'll never
forget the lesson.
