SUMMARY: Technical Writers and Programming (long)

[Mike Collier - SSG <MikeCol -at- SBSERVICES -dot- COM>]

About a week ago I posted some questions about technical writers and
programming skills.  I'm reposting the questions with the responses
summarized.  Even though many were posted to the list, I received some
excellent off-line responses as well.  Thanks to all who responded.

Michael Collier
mikecol -at- sbservices -dot- com
------------------------------------------------------------------------
------------------------------------
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?

Answers included the following:

*       Inspect header files to get the exact syntax for a function;
*       Ability to read object diagrams (writers took object oriented analysis
and design training)
*       read blocks of code, not write it (rely on developers to verify
accuracy of code examples)
*       one respondent mentioned his company hired a graduate student to teach
him C programming so the writer could develop sample code, sample
functions and a sample application.
*       basically, it helps the writer understand the programmer's process and
makes it easier to communicate with programmers.

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?

The general response was that these books are useful as a reference;
several people mentioned they only worked through about half of the
"Learn in 21 Days" books.  "Learn C in 21 Days" came highly recommended
by one respondent; "Learn Java in 21 Days" was filled with errors,
though it contained a good intro to object oriented principles,
according to another.  Several mentioned before buying a book, check
with programmers for what they recommend.  Live classes were considered
the most useful means, by those who could compare the results. Others
mentioned the web as a good place to find free programming tutorials.

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?

Some said 50-50, others said, clearly technical writing skills. It
basically depends on what you need to do for the job.  In the beginning
of a documentation project, you may have to spend a lot of time learning
the programming; towards the end, you're concentrating on the writing.
Others mentioned that they spend more time learning programming skills,
because that's the direction they want to move in.

One respondent pointed out that knowing code basics is important, but
you don't need to understand code intimately in order to document
functionality, or the user interface. Spend most of your time
understanding how the document will be used to serve an information need
of the end users.

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.)

Only one respondent mentioned that tests like those mentioned above are
used; most interviewers said they get a feel for the person's skills
through general discussion, asking probing questions, viewing their
writing samples (with code in them), and ask them how they developed
them.  Also, if they mention how they find sources for the latest build,
and how they us header files.

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?

Almost everyone felt this was asking too much.  Others felt it could be
done if you're documenting APIs or other internal documentation. Even
then, though, the writer would need access to header files and runnable
code , and would require a fair amount of programmer time for questions.
 Generally not thought to be a good use of a writer's time, and they
maybe looking to get a programmer at a writer's salary.

 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