RE: API Questions Please

Subject: RE: API Questions Please
From: "Richard Smith" <Richard -dot- Smith -at- windriver -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 10 Jul 2001 13:17:38 -0700

> I am interested in hearing more about API
> documentation. What are the basics you have to
> know for working in this area, employment and
> future work opportunities?

API writing is not the mystery many make it seem. You provide a complete
listing of the public routines/methods/interfaces/whatever your software
makes available, and show how to use them. For each, you provide
definitions, syntax, usage, explanations, and examples. It varies a bit
according to the language, but these are the basic elements. If the question
boils down to can you (or I) document APIs without knowing code, I doubt it.
At least not very well. You'll probably have a hard time finding such work
in the first place if you don't have at least working knowledge of the
language(s) your documenting. Best piece of advice I ever heard regarding
this: make sure all code examples come from working tested programs (I think
that comes from K&R). As for employment...I'll have to get back to you, my
magic 8-ball is broken right now.

>Is it a field that will become automated?

Heck, it's already there, to a degree. There are tools, like Doxygen, and
Javadoc, that will automatically create a very nice HTML (or other format)
docset from your code. However you still have to provide quality comments,
examples, etc.

Automation is only automation. Computers don't make decisions, they follow
instructions. That is to say, if your code has lousy comments, the automated
tools will happily produce crappy API docs. You know what they say; garbage
in, garbage out! When used wisely though, they can be a huge timesaver.


--
Richard


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

TECH*COMM 2001 Conference, July 15-18 in Washington, DC
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


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


References:
Re: API Questions Please: From: Palm906

Previous by Author: Re: TFM *g* (was: Creating Intradocument Links in Adobe Acrobat)
Next by Author: RE: The action of creating a JAR file
Previous by Thread: Re: API Questions Please
Next by Thread: Graphics to show speed?


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


Sponsored Ads