RE: Damnit Jim, I'm a technical writer, not a writer!

Subject: RE: Damnit Jim, I'm a technical writer, not a writer!
From: "Swallow, William" <WSwallow -at- courion -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 9 Jul 2001 15:30:06 -0400

:: But I still don't see why I need to also have a
:: programmer's skill set.

*You* may not need to. *Others* may. Knowing how to read code does not make
a good tech writer, but if it helps to understand what your application is
doing/is intended to do, then learn it. :)

:: I see many tech-writers who do not understand the
:: real-world context in
:: which the products they document are used. To me, this is a
:: much greater
:: travesty than not knowing how to write multi-threaded apps.
:: (For that
:: matter, I've also seen plenty of DEVELOPERS who tend to
:: work in that sort
:: of vacuum, too; seemingly unaware of how the real world uses their
:: product, and/or only familiar with the specific module
:: they're coding.
:: Very scary.)

I totally agree. But what a technical writer *should* know should be based
on *what* they need to communicate. If knowing XYZ technology/language can
only help strengthen the understanding, then why not learn it? At least
learn the basics, if not teach yourself how to program. I'm not advocating
that every technical writer learn programming languages to the degree where
they could develop these applications themselves (but if you want to hit
that mark, more power to you), but knowing a language enough to see why X
behaves this way and how it interfaces with Y and Z may be important. It all
depends on your audience and how technical you need to be with them.

To put this into some sort of manageable context, say you are documenting
the age-old peanut butter sandwich creation process. In some cases, you
could just say "git yer bread, git yer PB, and git funky wit it!" and your
readers would totally understand. In other situations, where your audience
may be dieticians, you may want to dive deeper into the process and explain
how certain proteins are processed more completely or more efficiently if
certain breads are used, or something like that. Knowing something about
nutrition and nutrient absorption may be beneficial in this case. Your SME
may tell you that combining low-fat PB with whole grain bread is a good
thing, but may not know that honey-oat bread, when mixed with sugar-free PB,
can cause the body to absorb higher levels of potassium, which is dangerous
to those with kidney disease. But if you know this, you're good to go. (OK,
so maybe a bad example. *g* And for the record, this was all fictitious. I
have no clue whether honey-oat bread and sugar-free PB - if there is such a
thing - is potentially toxic or not.)

:: It seems like a lot of TWs are trying hard to "legitimize"
:: themselves in
:: the eyes of others, and that learning code is the main step
:: they're taking
:: to do so. (Presumably so you can walk up to a programmer
:: and say "How
:: 'bout them subroutines?" in a chatty and confident manner...)

Actually, subroutines are yesterday's thing. Today's hot water cooler topic
is dynamic content loading via JavaScript. ;) But seriously, I agree.

:: I offer that writing comprehensive, helpful instructions
:: that demonstrate
:: a thorough working knowledge of the product is the most powerful
:: "legitimizer" of all. After all, that's what WE get paid to
:: do. And most
:: programmers or other SMEs either can't do that, or wouldn't want to.

That was my point exactly. But to go beyond the legitimization of your
existence at a company, to do a really good job for your readers you need to
know that which you are writing about, and then communicate that effectively
to them.

*****************
BILL SWALLOW
Technical Writer
C O U R I O N C O R P O R A T I O N
1881 Worcester Road
Framingham, Mass. 01701
T E L * 508-879-8400 x316
F A X * 508-879-8500
www.courion.com
*****************

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.


Previous by Author: OT: Bobby
Next by Author: RE: Understanding Programming & Code
Previous by Thread: Re: Damnit Jim, I'm a technical writer, not a writer!
Next by Thread: Re: Damnit Jim, I'm a technical writer, not a writer!


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


Sponsored Ads