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

Subject: RE: Damnit Jim, I'm a technical writer, not a writer!
From: "Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 9 Jul 2001 14:43:20 -0600



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


Previous by Author: RE: tech pubs organizational question
Next by Author: RE: ... what makes a resume stand out?
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