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: Programming vs. Technical Writing From:"Linda K. Sherman" <linsherm -at- GTE -dot- NET> Date:Thu, 13 Aug 1998 12:46:10 -0400
Lisa Meng wrote:
>
> This makes me think that technical writing and programming approach
> information in entirely different ways. When I write, I tend to present
> information step by step; the last thing I want to do is to skip a step and
> lose my reader. When the programmer writes code, he seems to look for
> ways to skip steps, or integrate several steps into one. His main concern
> is making his code short. Has anyone else noticed the same thing?
As a better-than-average programmer of 25 years' experience who also
does technical writing, I might have some insight into this.
>From the standpoint of describing procedures, I see little difference at
the abstract level between good programming and good technical writing,
except that in one case you're telling a computer what to do and in the
other telling a human being what to do.
Programmers certainly don't try to "skip steps" at all--if you skip a
step, the program won't function correctly. What a good programmer does
try to do is make sure that there is no unnecessary code in the program,
just as a good technical writer should eliminate redundancy, verbosity,
duplication of material, excessive cross references, etc.
What appears to you as "integrating steps" probably isn't that at all.
It's eliminating unnecessary duplication of code by putting re-used code
into a single routine and having other parts of the program execute it
as needed. However, the same number of instructions are still executed.
IMO the two big differences between programming and technical writing,
in terms of describing procedures at least, are:
(1) The task being described to the computer must typically be broken
down into many thousands if not millions of individual instructions; in
contrast, the procedures described by a technical writer typically
consist of a few instructions to perhaps a few hundred in unusual cases.
(2) The programmer has a very small, primitive, inflexible, and
unexpressive "language" to work with. The technical writer has a vast
and highly expressive language to work with.
Not surprisingly, but perhaps contrary to the prejudices of many people
on this list, most /*good*/ programmers are excellent writers, at least
when they put their minds to it. Unfortunately, most programmers are in
the bad-to-mediocre range, both as programmers and writers.
Of course, tech writers do many other kinds of writing for which there
is no analogy in programming.
