Re: Tech Writer - Why called such?

[Eric Ray <ejray -at- raycomm -dot- com>]

Anthony Markatos wrote:
> Our primary job is not to write about HOW the product works.  It is convey
> understanding of essential end user tasks accomplished with the product and
> how those tasks interrelate.  It is, in other words, conveying understanding
> of WHAT the product does to help the user achieve his/her business goals.
> We may properly digress from the WHAT and discuss the HOW, but all effective
> organization is based on the WHAT.

For some cases and some situations, this is correct. However...

> How can we be viewed as "adding value" instead of "a necessary cost of doing
> business" if something as basic as our agreed upon title is so out-of-wack?

It's only out-of-whack if you have a REALLY narrow view of what we do. 

I'm currently writing a Programmer's Reference Guide (API docs,
deferring
to the Javadocs for the implementation details, to be specific) to help
Java 
developers use the Java classes shipped with Product A so they can
customize Product A for their company, their needs, and their situation. 

In this case, my primary job is precisely to write about HOW the product
does WHAT, and WHICH aspects of Product A should concern which
developers
at which times. The original organization was by WHAT, but that was
virtually
worthless, because it's like giving a tech writer a list of HTML tags 
organized by WHAT they do (these make text bolder and bigger, these
establish
links or references among documents, etc) rather than organizing by 
HOW to use the tags to easily accomplish common or likely tasks. 

That is, I could write that the Blah API does foo and bar, but I
_should_ 
write that the recommended way to accomplish a specific goal is to use
the foo and bar classes from the Blah API. 

You bet I'm adding value. If not, then all of our customers will have
the
same ordeal that our internal developers are having in writing to these
APIs, and I wouldn't wish that on anyone. 

Eric