Re: Programming Languages for Technical Communicators

[John Posada <posada -at- FAXSAV -dot- COM>]

I'm going to attempt to offer a different perspective on this subject.

First, I am not a programmer and I don't even play one on TV. However, I spend 10 hours per day writing documentation for UNIX programmers and support technicians.

To be honest, I find NOT knowing their language helps me produce simpler, more comprehensive documentation.

Let me explain my primary goal in creating this documentation.

Right now, many of the day-to-day processes that could better be described as program maintenance is being handled by some very experienced and innovative programmers.  However, much of what they do could be moved further down the food chain to people that may be solid programmers, but not programming whizzes. My goal is to be able to document these processes so that with minimal additional training, the average programmer can take over the function and leave the top-level programmers more time to do what they do best...innovate.

An average process for me is to have someone (usually a programmer) create rough step by step procedure of what is involved to do something. I then document what they've written and as I go through the material, I make "notes".  I point out these notes by typing a short question and then apply the attributes Bold, Italics, and Underline.  I chose these three attributes since never in my right mind would I place this in a document and it stands out (and can be searched for)

Example: this is a snippet of instruction with how I place my comments:

Check the other server (which server is this?) for crontab jobs (management reports, restarts, cleanings). (check for what and what do you do?)

If I was an experienced programmer, I might know these answers and not realize that someone else might not.

Then, when my document is reviewed (usually goes through this process 3 times), they can either address my question or tell me it is irrelevant.

Just another perspective

John Posada, Technical Writer (and proud of the title)
The world's premier Internet fax service company: The FaxSav Global Network
-work http://www.faxsav.com      -personal http://www.tdandw.com
-work mailto:posada -at- faxsav -dot- com   -personal mailto:john -at- tdandw -dot- com
-work phone: 732-906-2000 X2296  -home phone: 732-291-7811
My opinions are mine, and neither you nor my company can take credit for them.

HEY! Are you coming to the NJ TechWriter lunch?  So far, about 10
of us are.  Ask me about it. 


  


-----Original Message-----
From:   Katherin King [SMTP:kking -at- BROOKTROUT -dot- COM]
Sent:   Wednesday, January 28, 1998 10:12 AM
To:     TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject:        Re: Programming Languages for Technical Communicators

I document software for the computer telephony industry and I feel I am
seriously hampered by my lack of knowing programming languages like C++
and VB. It limits my ability to communicate with our software
developers, and to "translate" (isn't that what we do as techwriters?)
their work into English.

Although I have a background in engineering (many moons ago), I have
never taken a "real" computer course; I don't really comprehend the
basics of programming, i.e. the theory and concepts. Yes, I can "wing
it," and I have picked up a lot just by interacting with the developers,
but I could definitely use formal training in programming.