Re: Asking for help . . . LOTS

Subject: Re: Asking for help . . . LOTS
From: Peter Neilson <neilson -at- alltel -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 19 Oct 2003 09:50:54 -0400


On Fri, 17 Oct 2003 09:41:42 -0600, <turnleftatnowhere -at- yahoo -dot- com> wrote:

This is about doing API documentation. Everything I've read on this list
seems to indicate that the process of documenting an API is hellishly
complex and only the very best alpha geeks of the documentation world can
manage it. Late yesterday afternoon the VP gave me the job of documenting
the API for my company's product. He and I are supposed to discuss the
project this afternoon.
[etc]

Each part of the API is a call with a name that is distinguishable
from the others. In the case of Java, it's a little weird, because
the "same" name can be reused, but that's not a bad thing. For example,
zap(int j) and zap(float f) are almost as different as if they were named
zap and fzap. (These examples are simpler than what you'll find in real
Java code.) They'll show up in the same portion of the source code,
and will presumably do similar things, but each is unique. (If this
does not make sense to you, write back immediately, because there's
more you need to learn before you proceed.)

Java provides opportunity for the developers to document as they write
the code. Indeed, they are to document it BEFORE they write it! You
are dealing with what I call developoopers. You will need to be inside
the heads of these guys, because WHY you use a particular API can be as
important as how. You'll be told, "I'm off that project," and be referred
to a junior person who is in the dark as much as you. You'll be told,
"I don't have time until after March." Offer to take the developer out
to dinner, or to buy him chocolate.

You should be able to see the design documents for the project. If
there are none, and if the original developers have left the company,
your job may be nearly impossible. If the design docs are three years
older than the code, they effectively do not exist.

For each API you must know at least these four things:
What it is supposed to do in a wide sense
What arguments it takes
What value or entity it returns
What (if any) side effects it has

Very Bad Documentation, the kind you may be expected to create in a
hurry, will document the "what it does" much too narrowly. It's easy
to write it very quickly, though. Here's a bad example:

The countWords() API increments the word counter.

Notice how it says less than nothing. What are these words? Are they
obvious from context? Where do I find out about them? What is the name
of the word counter? We've totally overlooked that the word counter is
inexplicably a 16-bit value, and its overflow is not handled properly.
In other words, there's a bug. Good documentation considers all those
things, even if not all of them actually show up in the docs.

I can guarantee that there will be bugs in the code. That you are
not experienced in writing software may blind you to them. Worse, the
developers may refuse to look at any you find. Check the bugs out with
other people, not on the project, so that you're sure you are right,
every time.

You should make yourself a list of all the API calls, each one with the
data types it takes as arguments and that it returns. It's possible
to get your Java IDE to produce this list for you. The number of them
will give you an idea of the scope of the project. Someone else on this
list may have an idea of how much time you'll expect to spend on each
one. When you've got the time estimates for the tiny parts, add 'em up.
Resist any tendency (yours or the VP's) to round the number down.
Multiply by your favorite fudge factor. YOU CANNOT do the job in less
than that amount of time, no matter what the VP's deadline is.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

HAVE YOU SEEN THE LATEST FRAMEMAKER PUBLISHING TOOL?

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web. The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for competitive pricing or view a live demo at: http://www.ehelp.com/techwr-l3

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



Previous by Author: Re: Tech writer job description needed
Next by Author: Re: Excellent "please review me!" text or cover pages?
Previous by Thread: Asking for help . . . LOTS
Next by Thread: RE: Asking for help . . . LOTS


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


Sponsored Ads