TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Without tools to extract accurate prototypes of code items, your job becomes
much more difficult and error prone. Your efforts are out-of-date even
before you've finished your code pass to gather the information, because
code pools are constantly in the state of flux even when management has
declared "code freeze."
You could ask all sorts of questions about what users of the API need.
Functions? Classes? Enumerations? #define's?
The beauty of tools that extract things from the code is that they are
written by software developers for software developers. This means that the
tools have already made most of the important decisions about what should be
documented. And they do it automatically.
I look at API documentation as having two parts. Part 1 is the reference
material: the exact syntax, arguments, argument types, etc. needed for a
given code item. Part 2 is the "how to." This takes a higher level view and
shows the user how things relate to one another, what sequence things should
be created in, etc.
We're using Doxygen [www.doxygen.org/index.html] (for C/C++, IVE) and
JavaDoc (for Java). Both are free. In both cases, the tool extracts not only
accurate prototypes but also specially flagged code comments. I make regular
code passes to assure that the specially flagged comment blocks have the
correct formatted and correct English. However, I admit that most of the
wording comes from the engineers themselves.
As it should be. Software developers know that they are expected to document
what they do. Even if their code is never exposed to the outside world, they
are expected to comment it. There are few -- if any -- reputable software
development companies who can afford to have uncommented code written.
The beauty of the tools is that they expose (if only internally) the
deliverables of the software developer. They make internal code reviews
possible, because there is no reason why the coding/commenting methodologies
should not be applied to the whole development process even if not exposed
or delivered to a customer. This is where you're going to want to take a
step back and make sure that you have buy-off from all of development and
that the company's coding standards are updated accordingly. "If you can't
be replaced, you can't be promoted." For engineers, "if you can't hand your
code off to someone new and have them understand, you can't be assigned the
new whiz-bang, cutting-edge projects." It is self-serving for both the
engineer and the company to mandate commented code. The tool then becomes a
policing agent while at the same time giving you 80% of your API
documentation.
Doing a code pass doesn't take that much time. I can then spend more time
(a) in making sure that the tools are run on the correct components and
exposes the right amount of information and (b) in writing
theory-of-operation, overview, how-to's, etc.
I love documenting API's, but I won't do it without tools. It's the only way
that I can assure accuracy at the freeze date and still make the delivery
date.
As you embark on your API documentation, I recommend that you start from the
output that tools can give you and then improve it from there based on
internal and external feedback.
Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com
> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of envvy
> harris
> Sent: Monday, April 23, 2001 8:14 AM
> To: TECHWR-L
> Subject: Help API Documentation?
>
>
> My company is looking for more information on creating
> API documentation for a potential client. I am the
> only technical writer we have and I think I understand
> the concept. However, can anyone help me better
> understand how I should go about creating this type of
> documentation.
>
> Ericka
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.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.
