RE: Help API Documentation?

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

Ericka asked about API documentation. Glenn suggested using tools to
automatically extract API information, and Walden responded to Glenn's post,
pointing out some of the cons to using auto-documentation tools. I've been
documenting our products' APIs for over six years, and I have to agree with
Walden.

I don't have much to add to Walden's post (thanks, Walden!), except to say
in my experience, I haven't seen documentation created with an
auto-documentation tool that I felt was as complete and easy to read as the
documentation created "by hand." Walden is very correct in pointing out the
benefits of using a source tool for comparing changes in source code, and I
recommend that approach highly (we use SourceSafe).

One thing I would like to add, though, is for someone like Ericka who seems
to be new to API documentation, it would be biting off a lot to try to
implement an auto-documentation tool when she's just learning about this
work. As both Glenn and Walden point out, it takes coordination and
cooperation from the developers, not to mention time on your part to develop
the information they provide. Even if an auto-documentation tool looks good
for your situation, I'd suggest using one in future projects, but not now,
due to the ramp up time it might require.

To respond to Ericka's post in other areas, Ericka, you didn't mention what
kind of API you're documenting. There are some excellent resources out
there, including several former discussions on TechWr-L. I'd seach the
archives if I were you; I know there have been some very informative posts
on documenting APIs.

Here are some other resources for you:

Susan Gallagher has two great white papers available at
http://pw1.netcom.com/~gscale/susanwg/cmindware/article1.htm. Scroll to near
the bottom of the page to access her papers: "Yesterday API was just another
acronym; today I have to document one!" and "Oh, oh! The job ad says OO."
These are excellent introductions to API documentation.

Recently, the Montreal STC sponsored a workshop on API documentation
conducted by Gordon and Gordon. I could not attend, but the outline looked
excellent. They are offering for sale the workbook from the workshop.
Details are at their web site at
http://www.gordonandgordon.com/apisandsdks.html#workbook.

Finally, I'd suggest looking at your competitor's documents to get some
ideas about what you'll need to provide for your users and what format might
be best. For example, we document ActiveX controls for Windows developers.
The majority of our users develop in Visual Basic, using our controls in VB.
We modeled our API docs on VB's docs, in part because we figured the user
would be comfortable with that format. We've certainly changed some things
that they do (for the better, we hope!), but it gave us a starting point.

Please feel free to contact me if you have more questions, or if you'd like
to see some samples of our work.

HTH,

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 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East, 
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline 
April 27. http://www.pdfconference.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.