Writing - Technical - Writing API Documentation

There are application programmers (who produce programs that people use to do tasks -- programs like Turbo Tax, or a college registration system), and there are systems programmers (who produce the programs that enable the application programmers to do their job, such as programming language compilers, operating systems, servers, etc).  An API is an Application Programming Interface. The typical case is that there is a product that provides a bunch of services or features (like Windows, for example) and an application programmer wants to make use of these services. She needs a way to ask the product for what she wants. That's where an API comes in.

See:

• http://nightflight.com/foldoc-bin/foldoc.cgi?query=api&action=Search
• http://searchwin2000.techtarget.com/sDefinition/0,,sid1_gci213778,00.html
• http://www.pcwebopedia.com/TERM/A/API.html

The set of functions that an operating system, such as Windows, Apple Macintosh OS9 or OS X, etc provides for such simple tasks as responding to the mouse clicking on the image of a button, are one API. What I am documenting for Selectica Inc is an API that enables programmers to have their programs talk to a server that is proprietary to Selectica, than enables people (through a GUI) or programs (through the API) to create and use sets of business rules that enable a web site to accept orders for complex systems -- systems in which each component may have an effect on what each other component can be -- if you want to order an automobile, you pick a brand, this enables you to see a set of models; you pick a model, this enables you to see a set of engine choices; you pick an engine and you are offered a choice of stick shift or automatic, and so on. If you pick the convertible, you might be offered only a V6 or a V8, but if you pick a sedan, there may also be a V4 or a straight 6, and so on.

In any case, an API writer has to go in and explain a whole boatload of functions (in procedural programming) or objects and classes (in object-oriented programming). The writer must be able to read code well enough to pick out the definitions of all the access points and data structures, then describe them in an orderly fashion for the programmer audience.

Tools used for documenting APIs? Framemaker (or, in some cases, Microsoft Word) for text formatting and layout. Javadoc (http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/javadoc.html#doclets) and Doxygen (http://www.stack.nl/~dimitri/doxygen/)and similar tools for extracting data definitions and class and method declarations. Perhaps Visio or other graphic tools to draw UML (Unified Modeling Language) diagrams or flow charts.

In software companies -- Silicon Valley, Route 128 (Boston area),
Triangle Park (Carolinas), Redmond Washington.

Either be a programmer who turned to technical writing (as I did) or be a very competent technical writer who learns enough about programming. There are some courses -- the Silicon Valley chapter has one coming up on June 22 about the politics of Javadoc: http://stc-siliconvalley.org/seminars/seminars.htm
Jim Bisso has a course (http://www.bitzone.com/training.html) and Berkeley and Santa Cruz extensions probably also have useful courses.

Pretty technical, believe me. 

I have enjoyed it. As a programmer, I was often at the mercy of the API documentor -- now the shoe is on the other foot, and I need to remember just how little the reader might know about our product and how much the development engineers have neglected to tell me that I must dig out and pass along. 

Learn to program. You don't need to have written a compiler or an operating system, but at least know some application programming AND some systems programming to be able to think like your audience.