RE: So what is API documentation anyway?

Subject: RE: So what is API documentation anyway?
From: "Jessica Weissman" <Jessica -dot- Weissman -at- hillcrestlabs -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 26 Mar 2007 07:48:13 -0400

The core of my job is documenting our API. The API doesn't quite fit
the list-of-objects-and-calls paradigm because there are a number of
separate components that work together to create applications in our

The chief challenges for me have been:

1) Getting the developers to give me information. I solved this (in so
far as it has been solved) by asking them as few questions as possible,
demonstrating that I could learn some of the system on my own, and
handing out plastic toys from Archie McPhee as bribes. $50 worth of
bribes got me a long way.

The real turning point was when I turned up at a group meeting in a
custom T-shirt labeled with the statement that, in our system, means
"ignore this object". I got lots of laughs and significantly more
co-operation. Evidently young programmers don't know that you can buy
stick-on letters and blank T-shirts at any craft store.

2) Understanding the new world of programming. I've done lots and lots
of coding, but most of it was in procedural languages or scripting tools
like Hypercard and Toolbook, with a light dusting of Visual Basic 6.
Neither JavaScript nor Java scares me any more. I'm not up to C++,

3) Figuring out which higher-level topics belonged in the documentation

4) Remembering to pitch the documents at the developers's level, not at
the beginner level where most of my prior work has been pitched.

It's the most fun I've had at work in years. And I've gotten to the
point where I can occasionally help the designers and developers by
pointing out missing items and inconsistencies in what we have defined.

I've been lucky in having solid support from management, who already
knew that Javadocs wouldn't be enough.

Jessica Weissman

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Re: So what is API documentation anyway?: From: Peter Neilson

Previous by Author: RE: Speaking of indexing...
Next by Author: RE: Tech Writers & Educational Material?
Previous by Thread: Re: So what is API documentation anyway?
Next by Thread: Re: So what is API documentation anyway?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads