Re: Documenting APIs

["Wing, Michael J" <mjwing -at- INGR -dot- COM>]

I don't know of any books on documenting APIs.  However, I am self taught on
most of my methodologies, approaches, and designs (yah, I'm one of those
that always has - or think I have - a "better" way to do things).  We had a
similar discussion about API documentation back in September.  The following
is what I do with API documentation and is modified from a post I made
earlier:

I document every object, method, property, event, and constant exposed to
the programmer by my product.  Each object topic links to it's methods,
properties, and events.  Each property or method argument that references
constants links to the applicable constant topics.

Each topic focuses only on that piece of automation (that is, the OpenFile
method explains the syntax, arguments, and implementation of that method).
If a method, property, or event topic has multiple implementations (applies
to more than one object), I explain any differences.  If the automation
element affects other elements, I explain in the Remarks section of the
topic.

In an object topic, I explain creating and implementing the object.  I also
categorize its properties, methods, and events into functional groups.  For
example, I may explain that the Document object has methods for file
manipulation (opening, closing, saving, and so forth), imbedding graphics,
and so forth.  I explain that it has properties for configuring the
appearance (background color, offsets, and so forth), ...

I do not document workflow in the on-line reference help.  My philosophy
is that for reference help, the user is in the midst of writing code and is
not
sure if there is a  method to perform a certain action or is not sure of the

syntax and whether arguments are optional.  Therefore, they press F1
(in VB) and get help on that automation element.

Workflow information appears in a companion document.  I do this document in
HTML with links to the automation topics (either other HTML pages or winhelp

topics).

The workflow document also contains complete examples of code (complete
being a full application command or function written in VB for the product).
I have
also embedded VBScript code and form controls in the HTML document.
This allows the user to execute the code from the help document.  For
example,
the user can set document parameters, and then they can automatically open
the document with it set to the customizable settings.  For ASP-based
applications,
I can execute ASP examples "in place" in the help file (using HTMLhelp).

To determine what to document, I extract API information from an object
browser.
Some browsers (like VB  Companion divide the elements into method, property,

event, constants, object categories).  The browser also tells you the
arguments for methods and events.   Good browsers tell you whether the
arguments are input or
output, required or  optional, and the data type.

The OLE2View browser also displays F1 helpcontext numerics (in HEX).  I've
won a few free tonics (sorry, I'm done south now, it's Cokes) from
Developers who claim that they put in the help context ids.

I have written a Word macro that takes the print file from OLE2View and
makes a primitive automation help file (even does
object-property/method/event-object linking).

Mike

Michael Wing (mailto:mjwing -at- ingr -dot- com)
Staff Writer/ Web Applications Developer
Intergraph Corporation; Huntsville, Alabama
http://maps.intergraph.com



> Does anyone know of any good books describing how to write API
> documentation?
>
> - tgrrr
> ----------------------------------------
>
> Enlightenment is to be intimate with all things; it is the practice of
> moment to moment intimacy.
>
> - Zen Master DogenEnlEasdlkfjpasld;fjas;ldf
>
>

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