Re: Documenting an API

[Sandy Harris <sandy -at- storm -dot- ca>]

Yanick wrote:
> 
> Can anyone suggest guidelines for what a good API document should include
> (aside from the input and output of each function with code examples).

You need to give a lot of other low-level detail too:

	error conditions, and how they are reported
	effects of each function
	data structures created
	any limitations built in to the underlying system
	  (e.g. maximum number of ...)
	debugging or trace techniques
	interface to the rest of the world
	  (e.g. if some functions open files, which of the standard
	    file functions do they call, and how do they handle a
	    failure of that call)
	...

but those aren't the central task. Any programmer can get much of that just by
looking at the header files, interface declaration, whatever. If those files
are well-commented, you may have almost nothing to do here. Just provide
pointers to the files.

The key part is that you have to explain the abstraction used. Programmers are
often "mappers" in the terms used in the "Programmer's Stone" papers:

http://www.melloworld.com/ProgStone/ProgStone.html

Your main job is to help them build a good map.

If your product is some sort of database, you need to describe

	how tables are built, named, indexed, ...
	what types of data are allowed
	whether default values are sometimes inserted
	  what values? when?
	...

By your address, it might be a CAD system. In that case, you need to describe
the models it can build, internal data structures, relation between functions
in the API, internal model and what is on the screen or printout, ...	

One related API that is documented online is the Visualisation Toolkit:

http://www.kitware.com/vtk.html

Another way to look at it is that the abstraction is a metaphor:

Alan Kay ("I invented object oriented programming and I can tell you that C++
is not what I had in mind.") claimed in one paper that the single most
important step in software design was choosing the right metaphor.

e.g. the standard WIMP (windows, icons, mouse and pointing) interface (which
he also invented) is based on a desktop metaphor. The metaphor is not followed
slavishly; you can put a trashcan on the computer desktop even though you
almost certainly wouldn't put it on a physical desktop. However, it drives
the whole design.

So perhaps your job is to explain the metaphor and show how the pieces of
the API fit into it.

If, as happens all too often, there is no coherent metaphor, just a bunch
of unrelated routines that have been labbeled "our API", then I'd be saying
(perhaps screaming) something along the lines of. "This API is broken.
Can we fix it, or should we just scrap it and start from scratch on building
a good one?"
 
> ALSO, can anyone refer me to a good example of an API document online or
> otherwise?

Have a good look at whatever your programmers use for the target environment.
Microsoft APIs if it is a Windows environment, or sections 2 and 3 of Unix
manuals, or..  Also look at the API docs for your compettors if you can.

There's a doc online on how to write modules to plug into the Linux kernel:

http://www.linuxdoc.org/LDP/lkmpg/mpg.html

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Take XML and Tech Writing courses online!  Our instructor-led courses
(4-6 hrs/wk) give you "hands on" experience at your convenience. STC members
get 20% off!  http://www.online-learning.com/index.html.
---
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.