Re: Technical Writers and Programming Skills

["Susan W. Gallagher" <sgallagher -at- EXPERSOFT -dot- COM>]

Mike Collier - SSG wrote:
>I have a couple of questions for technical writers who use programming
>skills in their jobs...
>
>What level of programming knowledge is required of you in your work ?
>For example, are you required to be able to read blocks of code and
>explain what it is doing, and/or do you write code samples for use as
>examples?

When I worked in an environment that was 100% Smalltalk, I was able to
read blocks of code and explain them. I did not, however, write sample
code. I usually had a tech support or programming resource to do that.

But at this job, I have supported Smalltalk, C++, and Java with bits
and pieces of Visual Basic and Delphi integration and a smattering of
PowerBuilder code. I can't reasonably be expected to keep up, nor can
I ask my writing staff to, so we concentrate on the concepts and rely
on the developers to verify the accuracy of the code examples.

That said, we do need to know at least a little bit about the languages
that the product supports (not necessarily the languages we can integrate
with), namely C++ and Java (we don't do Smalltalk anymore). Just being
able to split a line of code when it doesn't fit on one line in the
user manual requires some knowledge of the language. ;-)

>
>If you've recently learned a programming language, have you been able to
>learn effectively and apply what you've learned from books of the "Learn
>[whatever] in 21 Days" variety?  What other means have you used to learn
>programming?

Years ago, I took Basic and COBOL at the jr. college level. I learned
UNIX shell scripting (Borne and C) via a painful process of looking
up every function I wanted to use and learned sql from a positively
horrendous set of Oracle manuals. I picked up Smalltalk by osmosis
and read books for C++ and Java. Mostly it depends on the complexity
of the language, the complexity of the job at hand, and the availability
of learning materials.

>
>What is more important to spend your time on-- developing and refining
>programming skills, or other technical writing skills, such as using
>document production software and writing and editing ?

Depends on where you're coming from. I have two writers on my staff.
One came from a programming background and has been concentrating
mostly on improving her writing skills. One has a strong writing
background, so she's been concentrating on learning languages and
concepts.
>
>If you (or if you would) hire technical writers with programming skills,
>how would you evaluate their skills in a job interview (e.g., explain
>the inputs and outputs of a block of code, comment a block of code,
>write a simple program, etc.)

In my experience, either I find a writer who obviously knows the
programming language -- and you can tell from the way they talk and
the samples they show -- or I find a writer with lots of enthusiasm
who is willing to admit total ignorance of the supported language
(but maybe with experience in other programming languages). Writers
with programming experience aren't particularly plentiful in this
neck of the woods, so I don't get the chance to be fussy that often!
;-)

>
>I have seen some help wanted ads looking to hire technical writers who
>can write user documentation straight from the application's source code
>(I assume without analysis, design or other project documents to use as
>reference).  Isn't this asking too much, even of a skilled technical
>writer with modest programming skills?  If you've done this, how did it
>go?

You *might* be able to pull off a stunt like that in a structured language
like COBOL. I can't concieve of it happening in C++ <shudder>! From the
user interface, OK, but not from the source code. It certainly isn't the
most advantageous use of a writer's time.

Sue Gallagher
sgallagher -at- expersoft -dot- com
     -- The _Guide_ is definitive.
        Reality is frequently inaccurate.

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html