Re: Programming vs. Technical Writing

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.

L.
--
Linda K. Sherman <linsherm -at- gte -dot- net>
Computer Consulting Services -- http://www.cti-pro.com
Dysgwch Gymraeg! Learn Welsh! -- http://www.dalati.com


From ??? -at- ??? Sun Jan 00 00:00:00 0000=



Previous by Author: Re: Sales Manual
Next by Author: Re: Programming vs. Technical Writing
Previous by Thread: Re: Programming vs. Technical Writing
Next by Thread: Re: Programming vs. Technical Writing


What this post helpful? Share it with friends and colleagues:


Sponsored Ads