Re: Technical Writers and Programming Skills

Subject: Re: Technical Writers and Programming Skills
From: "Wing, Michael J" <mjwing -at- INGR -dot- COM>
Date: Wed, 14 May 1997 09:11:00 -0500

My responses interspersed.

>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?


Initially, there was no requirement. The original plan was for
programmers to supply VB examples, descriptions, and syntax
explanations. The writer was to mold this information into on-line help
and spend hours begging developers for information. However, the
examples received (when received) were one-line repetitions of the
syntax or arcane snippets of some test code (filled with calls to
non-defined, homemade functions). There was also no information
describing the interrelationship between the automation elements
(prerequisites, preclusions, and so forth).

Therefore, I took the initiative to learn VB and develop my own
examples. Developing these examples exposed the interrelationships
between automation elements, snags in programming the application,
syntax nuances, and so forth. It was especially useful because it put
me in the position of my audience (application programmers). I was
forced to use my own help as a learning tool.


>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?


I had some programming as part of my Electrical Engineering coursework.
Our company has in-house training. Employees can attend programming,
cartography, imaging, and so forth, classes with customers. I have
taken VB through these courses. I also read one of those fat "How to
Program with VB" books.

>
>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 ?


At the start of each section, I create some mini-applications using the
area of automation for which I am documenting. For example, I created a
GUI to manipulate the coordinate system for an automated mapping
product. Initially, for each section, I am programming much more than I
am writing. As the application develops, I fill in the method,
property, and event examples and I describe the syntax elements. Toward
the end of the document section I am writing about 90% of the time. At
this point, I only program to test out combination of automation
elements and "what if" scenarios".

Those areas that I cannot work with or figure out go into a focused list
of questions and issues to take up with the developer. It is amazing
how much more information I can get from them with a question like, "I
used abc method and did not get xyz results" rather than a question
like, "tell me how abc method works".

>
>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?


This is an "It depends" answer. If the writer is documenting code for
internal use, it may not be asking too much. In this role, the writer
may be an extension of the programming department. The need for the
writing position most likely stems from the crunch put on the
programmers' time.

As code becomes more reusable, documentation of that code becomes more
essential. For example, a section of code written for one product (say
to draw 2D lines) may be reused with some enhancements in a another
project (to draw 3D lines). The software design document plays an
important role here. If the writing candidate cannot read source code,
it defeats the programming department's criteria that the document be
written with minimum programmer involvement.

The other side of the "depends" answer is for external documentation.
Most software writing that I have done is concerned with manipulating
GUIs, commands, workflows, programming through automation, and so forth.
Very little information concerning source code makes its way to the
customer. For user information, the writer is probably more concerned
with the results of the code than the inner workings of the code. For
programming information passed on to users (such as for programming the
application), reading code assists the writer in creating and evaluation
example code, syntax, and the interrelationship of functional elements.

>
>Thanks
>
>Michael Collier
>mikecol -at- sbservices -dot- com
>

Mike Wing
INTERGRAPH
| Michael Wing
| & Principal Technical Writer
| Infrastructure Technical Information Development
| Intergraph Corporation; Huntsville, Alabama
| : http://www.ingr.com/iss/products/mapping/
| ( (205) 730-7250
| . mjwing -at- ingr -dot- com

>

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


Previous by Author: Re: on the fly
Next by Author: Re: Documenting Floating windows - how would you do it?
Previous by Thread: Re: Technical Writers and Programming Skills
Next by Thread: Re: Technical Writers and Programming Skills


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


Sponsored Ads