Re: Tech Writer - Why called such?

Subject: Re: Tech Writer - Why called such?
From: Eric Ray <ejray -at- raycomm -dot- com>
To: Anthony Markatos <tonymar -at- hotmail -dot- com>
Date: Tue, 09 Nov 1999 20:44:45 -0700

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,
to the Javadocs for the implementation details, to be specific) to help
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
at which times. The original organization was by WHAT, but that was
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
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
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
same ordeal that our internal developers are having in writing to these
APIs, and I wouldn't wish that on anyone.


Previous by Author: ADMIN: If it's not about technical communication
Next by Author: ADMIN: Re: a modest grammar suggestion
Previous by Thread: Re: Tech Writer - Why called such?
Next by Thread: Re: Tech Writer - Why called such?

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

Sponsored Ads

Sponsored Ads