RE: API documentation and background information

Subject: RE: API documentation and background information
From: "Steve Hudson" <cruddy -at- optushome -dot- com -dot- au>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 26 Feb 2002 19:52:01 +1100

Think about an programming book or language definition you have ever seen.
They try and include some lightly fluffy 'overview architecture' stuff, and
then get down to hardcore lists of functions with their parameters etc.

That's what I like to see, that way I can dive into the few initial
functions I need, and later start glossing up on the place in the scheme of
things. RAD baby, RAD!

Steve Hudson, Word Heretic
Word help and tools: heretic -at- tdfa -dot- com

-----Original Message-----
From: Steven Brown

First, how much background information (that is,
outside the JavaDoc) do programmers prefer/need about
the actual application? For example, if "the
application" were a car and Bob the Programmer is
responsible for only the doors, how much conceptual
information does he need about the doors and/or the
car? Does he prefer/need to know the doors' function
in the car's overall design? Does he need to know how
people use the car? (I offer this example with
Japanese auto manufacturers in mind, recalling their
success is due, in part, to ensuring that their
engineers are exposed to the entire driving
experience, not just to their one area of

Second, for those of you who've written background
information, have you had any success with presenting
it in a format that's more "approachable" than a
traditional, systemic presentation? For example,
there's a series of books about programming languages
called "Who's Afraid of..." by Steve Heller. He
presents very complex information using a Q&A
discussion between an expert and a novice. I'm
thinking that I could use a similar approach to
present information about our application. I'm eager
to consider new approaches if they increase the chance
that programmers will read (what I hope is) useful

Now's a great time to buy RoboHelp! You'll get SnagIt screen capture
software and a $200 onsite training voucher FREE when you buy RoboHelp
Office or RoboHelp Enterprise. Hurry, this offer expires February 28, 2002.

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.

API documentation and background information: From: Steven Brown

Previous by Author: Word: Nasty little surprise
Next by Author: RE: Menu: what to call it
Previous by Thread: RE: API documentation and background information
Next by Thread: RE: He said...She said...He said...etc. (Was Re: What's A TW Got To DO To Get A Job Around Here?!)

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

Sponsored Ads