How much experience for API writing?

Subject: How much experience for API writing?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 8 Mar 2002 09:52:04 -0500

Anonymous wonders: <<how much programming knowledge you need before you're
qualified for this type of work.>>

As in any other kind of documentation, you must have enough knowledge to
write procedures or explanations that work. This means that you have to
understand what the reader will try to accomplish and how they're likely to
try to accomplish it. Moreover, you need to understand the basic concepts.
Think of this as the difference between writing an actual procedure and
writing a description of a procedure: the first requires you to understand
each step and what it involves, whereas the second simply tells you what
those steps are without telling you how to do them.

For describing an API, the task might break down (simplistically) into the
following elements:
- what a function does (all the various settings, plus examples of each) and
when to use it
- when _not_ to use it, and what the alternatives are
- what other functions interact with the function being documented (i.e.,
cautions, problems, logical combinations of functions)

Talking to the developers will give you an idea of what other components to
include in your description; they should have a clear idea of how real
programmers will use the API. Your role is to understand each of these
components of the docs well enough that you can write a good explanation of
each (and thus, of the function as a whole). You may never need to be able
to actually create a complicated program (i.e., to link a bunch of API calls
together into an efficient, logical, error-free sequence), but you must be
able to decide that if you _were_ going to use an API call, you'd konw when,
why, and how to do it.

<<Currently, I'm taking a C++ class.>>

This should probably give you all the basic programming knowledge you need
to know to do the job.

<<The second C++ isn't offered, so it's a choice between Database or Java

Database development is important, and teaches a set of thinking skills that
go beyond the ones you learn in a general purpose programming class. It
would give you more thinking tools related to software development, but
might not relate directly to your current work (e.g., if you're not
documenting a database API). Java will give you a deeper grounding of what
you've already learned (C++), and probably has a bright future given how
Web-crazy everyone is these days, but won't be hugely different from what
you're already learning in C++. Which is more relevant to your current and
future plans?

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at

"Any sufficiently advanced technology is indistinguishable from a
personality, and an obnoxious one at that."-Kim Roper

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.

Have you looked at the new content on TECHWR-L lately?
See 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 for more resources and info.

Previous by Author: If you were gonna teach...?
Next by Author: Ranges in index entries?
Previous by Thread: RE: How much experience for API Writing?
Next by Thread: RE: Summary: True insignificance... and release notes

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

Sponsored Ads