RE: the dearth of documents on documenting APIs and SDKs

["Lydia Wong" <lydiaw -at- fpoint -dot- com>]

Mandy Wells asked (in part):

> Why is that? And, why haven't one of you brilliant API/SDK documenters
> documented the process and sat back to rake in the millions of
> dollars (OK,
> hundreds...hmm, maybe tens of dollars) flowing in from grateful
> not-technical writers like me?

Well, I can't speak for all us "brilliant API/SDK documenters" out here ; ),
but speaking for myself, here are the reasons:

1. I have a life. It's not computers and it's not writing. I spend 8 or more
hours a day at work, getting paid (nice money, I admit) to document our
products' APIs. The rest of my time is for spending time with my family and
extended family, walking, reading, and many other things that don't involve
computers and APIs. That way, when I am spending time working on computers
and APIs, I don't hate it. (Actually, a lot of the time, I like it.)

2. I would not feel that I was an expert. In part because I know some other
API/SDK documenters, and what they do isn't just like what I do. Yes, what
other API documenters do is similar in many, many ways, but it's not exactly
the same. (Part of this fuels the discussions on this list concerning use of
automated API doc tools, I think.)

3. Personally, I know VB pretty well, I guess, but I don't know Java, C++,
C, etc. Documenting APIs and SDKs differs depending on your audience and
your product. A workbook like the Gordon and Gordon workbook confirms many
of the similarities of documenting APIs/SDKs, but also points out some of
the differences. I don't know enough about those differences to write a
book!

4. Ditto what Walden said, "its the 'tens of dollars' that stop me from
writing a book." ; )

There are other resources besides books: Susan Gallagher has kindly posted
two excellent white papers to her web site. You can find them at
http://pw1.netcom.com/~gscale/susanwg/cmindware/api.htm and
http://pw1.netcom.com/~gscale/susanwg/cmindware/ohoh.htm. Susan (I think it
was Susan?) has also asked folks about presenting/planning more advanced API
sessions at next year's STC conference. Keep an eye out to see what develops
there.

Finally, search the archives here at TechWr-L. There have been API
documentation discussions off and on over the years, and some have had
excellent information and advice.

Lydia
__________________
Lydia Wong
Technical Writer
FarPoint Technologies, Inc.
www.fpoint.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.