API documentation and background information

Subject: API documentation and background information
From: Steven Brown <stevenabrown -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 25 Feb 2002 10:00:41 -0800 (PST)

Hello all,

I'm working on API documentation for a Web service. I
understand the types of documentation that generally
accompany APIs, but I have a couple of specific
questions for those of you who have a thorough
understanding of how programmers who use APIs use the
documentation.

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

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

Your thoughts please.

Steven Brown
Senior Technical Writer


__________________________________________________
Do You Yahoo!?
Yahoo! Sports - Coverage of the 2002 Olympic Games
http://sports.yahoo.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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. www.ehelp.com/techwr

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



Follow-Ups:

Previous by Author: Re: Benefits of FrameMaker
Next by Author: Re: Revisions into Frame
Previous by Thread: Yikes...tread carefully (was RE: Resume format)
Next by Thread: RE: API documentation and background information


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


Sponsored Ads