Re: YOWZA--struck a nerve: Was Help API Documentation?

[Yvonne DeGraw <ydegraw -at- home -dot- com>]

Emily sounds like she feels she's alone in a corner with her argument, so I
thought I'd offer a little support and try to strike some middle ground.

In my experience, there are several parts to any API reference topic. The
first parts are typically things like:

o API function name
o Short description of API function
o Overall syntax for calling API
o List of parameters with datatypes and one-line descriptions

It is reasonable to expect that given the right tools, all of these things
could be generated from the code and comments in the code. I've done that
before, and it can lead to much higher accuracy. 

In fact, since I was working for a database company, the doc department put
all that stuff in a database. Then, from the database we generated "jacket"
calling functions for the software itself and syntax and quick-reference
descriptions for the documentation. So, to change their code, the
developers changed the same database the doc department used. (It was a
database company, so we used databases for everything.)

Then, the API topic continues by including things like:

o how to use the API function
o calling constraints
o examples of use
o "see also" references
o (and somewhere in there you need index entries)

I agree with Emily that this is our part, and should be maintained as part
of the doc, however that is done. Looking at the code is useful, and I do
it plenty. But, in my experience there are always things that need to be
described about how to use and not to use each function that wouldn't be in
the source code. 

Examples might by that API_abc calls API_xyz, so the description of API_xyz
needs to say that you shouldn't call API_xyz if you've already called
API_abc. That information wouldn't be in the code for API_xyz, because
programmers write functions to be self-contained. It's implied in the code
for API_abc, so when you write the description for API_abc, you ask the
programmers whether API_xyz can be called twice and if not add a note to
API_xyz. 

While you can get the actual actions performed by an API function from the
code or a programmer, the API's "side effects" are not something that the
programmer is going to think about putting in comments because they don't
have a user focus when writing comments. 

-- Yvonne
~~~~~~~~~~~~~~~~~~~~~~~~~O-O-O~~~~~~~~~~~~~~~~~~~~~~~~
Yvonne DeGraw                   * Technical writing
ydegraw -at- home -dot- com                * Online & web help
Tel: 805/683-5784               * Instructional design
http://members.home.net/ydegraw * Database publishing
~~~~~~~~~~~~~~~~~~~~~~~~~O-O-O~~~~~~~~~~~~~~~~~~~~~~~~
Manager, STC Instructional Design & Learning SIG, www.stcsig.org/idl

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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