Re: Documenting APIs

Subject: Re: Documenting APIs
From: Chris Despopoulos <cud -at- ARRAKIS -dot- ES>
Date: Tue, 6 Apr 1999 16:13:06 +0200

I can't say I'm aware of any books about documenting APIs.
But there are plenty of examples. I believe you can find
all the Adobe SDK documentation on their web site... Just
look around. Interestingly enough, the documentation is
different for each SDK. In my work on the Maker FDK docs, I
believe that is because each API has a different character.
For example, the Maker API requires a good knowledge of a
Maker document, its archetecture, and what all the possible
document objects can be. Without that, you can't really
plan how to use the FDK functions. I mean, finding the
insertion point is a problem all its own in the FDK. The
other SDKs are not necessarily as reliant on the hierarchy
of data structures. Also, resource constraints (time and
money) come into play, as well as the fact that often an API
documenter is not primarily a writer. (The last remark is
not meant to imply ANYTHING whatsoever about Adobe Systems
Inc, or any companies I have worked for or ever will work
for.)

I would say you need to start from the top-down. Understand
the technology associated with this API. Then understand
what people will want to do with the technology, and how or
why they would want to extend it with the API. I believe
this information is always valuable in the docs... You
can't assume an API user is a fluent user of the product.
Once you have that, then you can start documenting the
functions and data structures. And I am a firm believer in
having a good example with each function discussion... If
the examples turn out to be too trivial, lump a number of
functions into one example and refer to it from each
function discussion.

Be sure to document all data types that are not native to
the programing language.

Finally, each function discussion should include the
following:

* Synopsis/prototype
* Purpose
* Arg description
* Full list of possible returns
* Detailed description, including listing of associated
data types
* Typical example, including cleanup if required
* References to related functions and data structures

Oh... so this is a comprehensive guideline??? AS IF!!!

Good luck cud

From ??? -at- ??? Sun Jan 00 00:00:00 0000=




Previous by Author: [Fwd: What if Dr. Seuss wrote technical manuals]
Next by Author: Re: naming conventions
Previous by Thread: Documenting APIs
Next by Thread: Re: Documenting APIs


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


Sponsored Ads