TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> -----Original Message-----
> From: kcronin -at- daleen -dot- com [mailto:kcronin -at- daleen -dot- com]
> Sent: Monday, July 09, 2001 1:08 PM
> To: TECHWR-L
> Subject: Re: Damnit Jim, I'm a technical writer, not a writer!
<snippage>
> But I still don't see why I need to also have a programmer's
> skill set.
>
> I DO need to be able to converse intelligently with
> developers, but how deep do you have to go?
> Do we also need to delve into the assembly
> language created by whatever development tools the programmers use? At
> some point, I think enough is enough.
You're absolutely right. And so is Bill. You're just splitting hairs.
FWIW, even programmers with the skill set do not understand everything.
When working on a team, they understand the boundaries to their
teammates' code, but only the gory details to their own code.
Documentation always boils down to "what is the input; what is the
output; what gets modified; what gets destroyed; when is it used." How
the output is achieved is where I draw the line.
FWIW, engineers don't always like talking about how it was achieved,
because:
(1) in keeping with a Black Box concept, the underlying mechanism should
be interchangable. Exposing it to users defeats the freedom of being
able to swap it out from underneath the user with something better.
(2) maybe the implementation is so simple, the engineer is embarrassed
that the company is charging so much for it.
(2) maybe the implementation is so complex, the engineer is mercifully
sparing us a situation where we're forced to yawn with our mouths closed
while straining to keep our eyes opened and focused.
The way I figure it, anything that is exposed to the user has to be
documented. If an API is exposed, the API and its associated elements
(e.g., required for its usage) are exposed. If only a dialog box is
exposed, then everything the user needs to know to use that dialog box
is exposed. In both cases, I won't go into details about an underlying
structure (such as a database) unless understanding that structure
facilitates understanding the how's, why's, and when's of using what we
do expose.
In supporting your comments about "enough is enough" from my personal
experience, rarely have I ever traced code all the way from its obscure
input to its bitter output. (They don't pay me enough for that, anyway.)
However, I do need to know enough to trace code forward and backward
from a given point (e.g., a filename & location from an engineer) to get
what I need. I need to know how to figure out what something was (e.g.,
C++ class of type X) and what it uses (e.g., member functions). Armed
with this information, I could approach the culprit engineer and ask why
and when.
> 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.
Well stated. The key phrase is "a thorough working knowledge of the
product."
IME, engineers know their corner of the code, but not the system. For
that matter, any application that is NOT directly related to computer
science may already be outside of their field of expertise. (A drafting
package, an accounting package, an electrical engineering package, a
documentation package, etc. are outside the scope of what you learn
getting a C.S. degree.)
The tech writer has to have enough system and application knowledge to
be able to describe how this particular implementation meets the
customer's need in that application area. They have to span the
low-level subsystems to explain what is relevant to the user. Sometimes
the users don't need to know what's underneath, and sometimes they do.
This is where tech writers add value, because they're the first to
approach it like ignorami with nothing and come up with the roadmap for
the users to get something. Whereas the engineers might be building the
roads (applications), they aren't driving on them daily for any distance
both in and beyond their neck-of-the-woods -- if they drive on them at
all -- like an interstate truck-driver (application engineer, customer)
does. The tech writer has to take the first test drive, mark all the
on-ramps and exits, post speed limits and direction signs, and do the
complete tour to make this new stretch of road (application) useful to
the driver (customer).
Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com
Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- 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.
