RE: Help API Documentation?

["walden miller" <wmiller -at- vidiom -dot- com>]

I am also an API writer.  I prefer it because I get into code on a regular
basis and I started out as an engineer, but don't get to write much code
anymore.

I do not use auto-documentation tools however.  I prefer to either
understand the code itself or require specifications that are outside the
code. I have used doc tools and I like them for generating the basic
structure, but don't like them for generating the body of the explanations
for API functions.

> 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 can generate new prototype documents easily, but I must ask how well one
can generate example code, prolific explanations (when necessary), etc. in
addition to the prototype information. Essentially, all of this must be
non-generated or at least heavily edited before ready for prime time.
>
> 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.

This boils down to trusting the engineers to keep their source code comments
up to date.  Often this is not done.  The comments stay within the realm of
accurate, but the only way to know if the comment is accurate is to
understand the code to begin with.  By the time you have corrected all the
comments, both grammatically and technically, you have essentially written
that page in the manual.

By using windif or diff or whatever source change tool, you can track actual
changes to the code and make the necessary documentation changes.  This does
not rely on engineers to update specs or comments.

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

I agree that the two parts are very important.  I think a third is equally
important: the tutorial on building some code modules (whatever you think
the target audience of engineers need).

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

Another good tool is George.  It is not free.  But it has great output to
FrameMaker.

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

I disagree.  Software developers should be able to write specs, but not
expected to write polished documentation. Also, I work with many many
foreign engineers.  English is their second or third or fourth language and
it takes them incredibly long hours to write small sets of comments/specs.
Whatever they write must be heavily edited.

> 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.
>
Again, this assumes a great deal.  I work in the bleeding edge industry of
interactive television middleware.  Commented code is the exception because
of the huge number of foreign programmers.  And because most middleware
companies are in the Valley, there is a great deal of turnover, except for
the foreign programmers (who are locked in until their green card comes
through after 3-4 years).

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

Writing the API function information takes very little time.  Writing the
Programmer's Guide and Tutorial are the real schedule breakers.  API
information can be kept up-to-date easily without tools. BUT...
If you have the right engineering staff and the right documentation staff
and ...., then tools are way cool.

Walden Miller
Vice President, Engineering Services
Vidiom Systems


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

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