Writing : Technical : Writing API Documentation
Last updated: 6/16/2002; 10:21:45 AM
The FuzzyBlog!

Marketing 101. Consulting 101. PHP Consulting. Random geeky stuff. I Blog Therefore I Am.

Writing : Technical : Writing API Documentation

This essay was shamelessly stolen from an email by http://guy.blogs.at/.  Guy K. Haas knows more about tech writing (heck, just writing) then I ever will.  Writing API documentation is something I've never understood so I jumped at the chance to get the email and thought… Hey!  Blog that puppy.  With Guy's permission, I now have.

What is 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.


What are the different kinds of API documentation?

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.

What are the common tools used?

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.

Where are the typical jobs for API writers?

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

How can a writer get into writing API Documentation? & Is there any specific training one needs to take?

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.

How technical need the person be?

Pretty technical, believe me. 

What would you like to say about your career as a API writer?

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. 

What is your advice to students who want to become API writers?

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.

Copyright 2002 © The FuzzyStuff