Re: FWD: How much experience for API Writing?

[Zack Brown <zbrown -at- tumblerings -dot- org>]

On Fri, Mar 08, 2002 at 06:24:31AM -0700, Anonymous wrote:
> I have a couple of questions about API writing. Basically, I'm wondering how
> much programming knowledge you need before you're qualified for this type of

> Also, I would appreciate input the general pay rate for this type of
> writing, what type of structure is used in the documents, and anything else

Hi Anonymous,

I do quite a bit of API documentation for my company. Programming
knowledge is helpful, to the extent that it allows you to understand the
code what the developers' explanations. Being able to write a program
that uses those APIs is a good thing, but it is just a way to be sure
you know what information is important to include in API documentation.

However, it is no guarantee of having that knowledge. I've found that the
following information is always desired, and I don't think programming
knowledge is required, *if* you see the need to describe this information
(and if the developers are willing to give you the details you lack the
programming skill to find out for yourself):

1) The name of the function

2) brief description of the purpose of the function (not necessary if
this is obvious from the name)

3) The function definition (from the .h file)

4) a complete description of all possible return values and under what
circumstances they may be returned.

5) a complete description of all side-effects that may result from
calling the function. If you think of the system as a state machine, the
side-effects include everything that has changed in the system as a
result of the function-call, and that may affect the way other parts of
the system run; excluding the return values. Some examples:

    5a) data going into a socket. What is the protocol being used? Where
is the data going? What parts of the system are reading from that
socket?

    5b) input parameters that are actually pointers, whose value is
altered by the function. I call these "output variables"

    5c) changes to hardware configurations

There are plenty of other things. Those are just a few to note.

6) any additional description of what the function does, special cases
when it should and shouldn't be used, or when it may behave differently
than expected.

7) The path to the .h file, if it will be made available to programmers
(which presumably it will if they'll be writing code against it)


Now, one thing you definitely *don't* want in an API description, is any
discussion of implementation details. Implementation details are the way
the function accomplishes what it sets out to do. This can be tricky,
because sometimes the way something is implemented causes a side-effect,
and in order to properly explain the side-effect, you must make reference to
the implementation. Developers tend not to like that, because it threatens
to lock them into a particular code-base. But sometimes it's necessary.
Be prepared to explain (nicely and in a non-threatening way, and did I mention
nicely?) exactly why you had to include implementation in the doc. The reason
is that as soon as it has an appreciable impact on the rest of the system,
it ceases to be an implementation detail.

One thing you need to take into account is that APIs change, and an API that
is undocumented can change a lot easier than one that *is* documentated,
because it may be that no one (or only very few people) is depending on it
to behave the way it behaves. So expect developers to preface everything
they say with, "now this is all about to go away and be replaced by the
uber-interface-of-tomorrow, so go write about something else." Related to
this, they will almost certainly say that, at the very least, parts of the
API are not done and need more work. My way of handling this is to thoroughly
document the core ideas that will not be changing, and then make a guess
at the most stable portions of the API and document them, and then make a
guess at where the API is likely to be in a realistic time-frame and document
that. Developers will often be much more willing to talk about future APIs
than current APIs, so don't get sucked into a too-distant fairy-land.

As far as salary, I'd love to hear what you find out.


-- 
Zack Brown

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check it out! Get some cool freebies when you buy RoboHelp! You'll receive
SnagIt screen capture software and a 10% discount voucher for RoboHelp
Consulting. This special offers expires March 29, 2002.
www.ehelp.com/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

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