TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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!!!
