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.
Paul Hanson asks for opinions on: <<If a programmer has to write up a spec
with the information that is used to create help text, why not have the
programmer create the help text? Why have a duplication of effort, since the
help text is
information from the specs? If a .hlp file is to be created, why can't the
Technical Writer just edit out the program changes, like changing calls
from File A to File B (assuming the change has no impact on the user), and
have a .hlp file?">>
Am I correct in assuming that you, like the rest of us, work in a place
where the spec approaches reality about as closely as science fiction
approaches science? That is, it bears a nodding resemblance to reality, but
there are some liberties taken with the facts to make for a good story*. If
not, it's dimly possible that this statement is correct: maybe you do work
at the Shangri-la where people actually create a useful, user-centered spec
and build the program code around it. If that's the case, you're out of a
job. <g>
* No flames, please. I read SF and write it myself. I'm just arguing by
simile, OK?
Were it me, I'd do what I've actually done once (in a different
context--"why do we need editors?"): stand up at the meeting with a
dictionary in hand and point out that this recommendation is like handing a
publisher a dictionary and wondering why you need the author at all. "All
the words are in the dictionary, so why bother getting the author to do
anything more than edit out the words that aren't actually being used in the
current bestseller." When the laughter dies down (or when they subside into
a sullen silence and start sharpening their knives), you can point out that
a well-written spec usually says what the _program_ does, whereas the help
file must say what the _user_ does. Although the former dictates the latter
to some extent, they're not one and the same thing. You might also want to
mention my sig line (see below) if you really like living dangerously.
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
