RE: API documentation?

["Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>]

> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of
> Zaigham_Khan -at- netsolpk -dot- com
> Sent: Friday, May 04, 2001 5:32 AM
> To: TECHWR-L
> Subject: API documentation?
>
> Hi all,
>
> Can somebody tell me the layer on which the API's work,

API (Application Programming Interface) have many layers and flavors. Some
require you to compile code. Some are interpreted. For example, the Visual
Basic extensions for Word for Windows can be considered an API.

API's typically are the exposed classes, member functions, and friend
functions that are needed to use some more powerful, underlying software.
The underlying software is a "black box". The user's can't see inside it to
learn how it does something. The user's don't need to know that; it is
enough that they know that it does something and what they have to do to get
it to do something.

In my case, however, we have two layers. One layer lets you program in
C/C++. Another layer lets you program in IVE, a proprietary internal
language and like Pascal.

> How is API docmentation done and

I use tools to extract (at the very least) the code prototypes from the
code. This assures me of their accuracy. In some cases, I also extract code
comment blocks. (I've been given permission to modify code comments.)

Material about how to use the API is maintained separately. In other words,
the sequence that code items should be created/called in, special
techniques, etc.

> whats the worth of these people who can do it.

These types of technical writers are usually very technical. Hence, they can
earn more money than somebody who just writes well.

They can be just as valuable as one of the "average" engineers on the
project and could be compensated accordingly.

Why? The programmers are doing all the work coding so are more important,
right?

Yes, but in the case of an API, it is designed for someone else to use it.
If the API isn't documented well, user's can program to it, they can't
accomplish their objectives, and the whiz-bang features of your programmers
aren't being used no matter how good they are. In some cases, if you can't
prove that the API is well documented, you can't make a sale to technically
savvy decision makers at your customer's site.

In addition, if your API isn't documented well, it means that more customers
will be calling expecting support. Sometimes, the only people who really
know are the engineers. If the engineers spend their time answering
questions from customers, they aren't programming new features.

Hence, an API Technical Writer adds value to the company in (1) reducing
customer support costs, (2) reducing engineering time in supporting
customers, (3) accelerating the customer's time to market with their
application using your API, and (4) helping make the sale by proving the
API's existence.

Hence, if you want to increase your "worth" to the company, you need to
bring up these points during your next salary negotiation.

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

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

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