Re: Hideous grammar

[Win Day <winday -at- IDIRECT -dot- COM>]

Janet Christian has contributed to an ongoing argument about whether
technical writers must be able to read code.

<snip>

>At every software-based startup company for which I've worked, we didn't
>even bother interviewing technical writers who did not have a programming
>background. The writing was just too complex and low-level, and the source
>material was too sparse. We frequently had no source material other than
>the code listings and the notes we took when attending the engineering
>meetings.

>There are certainly markets for technical writers who have backgrounds
>teaching English or degrees in journalism. They simply were not the places
>I have worked.


Janet, I do NOT agree with your assertion that technical writers who
document software must be able to read the code.

I write software manuals (among other things) for a small process control
engineering company.  My client's main product is the _engineering_; the
software packages are part of that.  All the software is written in Lahey
Fortran, not C.

I haven't even tried to read the code.  The engineers don't expect me to.  I
wasn't hired to read code.  I was hired because my background (chemical
engineer) is identical to my client's USERS' background.  I can sit down
with the product, and try to do all the things the USER will try to do.

When I can, I walk through every screen, and through every possible choice
on every screen.  I meet with the engineers as the software is developed,
and make sure the USER'S point of view is represented.

I made one software package, currently under development, crash and burn in
ways the engineers couldn't begin to imagine when we started, because I
tried to make the package do things it wasn't designed to do, just like the
users will try.  Needless to say, that package went back to the drawing board.

Many of these packages don't run on PCs.  They're written for the IBM RS6000
and other similar large computers.  (The software packages control
operations in refineries, chemical plants, and gas plants.)  Even the
engineers can't test the entire code inhouse.  Final testing is always done
during installation.

When dealing with packages I can't run myself, I rely on the engineers.  I
hang out in their offices during the course of software development.  I sit
with them while they design screens.  I talk to _their_ clients about
features - what's missing, what could be improved.

But I don't read code.

Win
----------------
Win Day
Technical Writer/Editor
Email: winday -at- idirect -dot- com