How much experience for API writing?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

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

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
www.raycomm.com/techwhirl/usersadvocate.html

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