RE: API documentation and background information

Subject: RE: API documentation and background information
From: "walden miller" <wmiller -at- vidiom -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 25 Feb 2002 11:21:52 -0700

Steve asks two questions:

First, how much background information (that is,
outside the JavaDoc) do programmers prefer/need about
the actual application? ...

Second, ...have you had any success with presenting
it in a format that's more "approachable" than a
traditional, systemic presentation?


In my experience, programmers don't write just a part of an application
without knowledge of the entire application.
One programmer may write a runtime engine, while another writes UI routines
that tie into the engine, etc.

PLUS, you never know what programmer will write which parts, so the process
of writing applications must be thoroughly documented. This may include
compile and test issues, in addition to the mundane code writing info.
Javadoc API docs rarely do more than skim the surface of what I would call
an application guide. I recommend more information than less.

As to your second question, I like to read about programming from an
informed perspective. Talk to programmers who used the API (or write an
application yourself to see what it takes) and interview them on application
skeletons, required code, typical gotcha's, etc. From your notes in talking
to engineers, you can build up an idea of what information is required.
>From the information quantity and type, you can develop a style that best
fits the data. (It is never a good idea to decide on a style before you
understand the limits and requirements of the data). The style doesn't have
to be traditional, but it does have to meet the needs and expectations of
your audience--engineers.

my .02

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: RE: Unsolicited resumes
Next by Author: Why I became a technical communicator
Previous by Thread: API documentation and background information
Next by Thread: RE: API documentation and background information

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

Sponsored Ads