Re: API documentation

Subject: Re: API documentation
From: Anne Chenette <achenette -at- eintelligence-inc -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 01 Sep 2000 18:18:22 -0500

Regina,

I've never used DocJet, but I have a little experience with three other
tools: Javadoc, dtd2html, and idldoc.

In a previous job, I used Javadoc to create reference material for a
programmer's guide to a Java API. It saved me a lot of time.
(Actually, the developers created the doc each time they updated the
code.) I was lucky - the developers wrote great comments in their
code. I did a light edit, and once I suggested some summary paragraphs,
but that was all. I wrote overview help and examples in FrameMaker,
then converted it to HTML files that included links to the Javadoc
reference information.

I used dtd2html to create reference material for an XML DTD as part of
an XML API (actually, for the same product). It was a bit more work
because the text is kept in separate files, which I created, then
updated each time the DTD changed. But it was very easy to set up. The
format was different from the Javadoc information, but not enough to
lose sleep over. (This was a rush job for just a few customers, so I
decided not to spend time on minor formatting issues.) One caveat:
dtd2html is written as a UNIX utility, and requires Perl; I think it can
run on Windows, too, but doesn't have a GUI interface. (I had a
friendly developer to help me install and configure it.)

In my current job, the developers use idldoc to create internal
reference information for a CORBA IDL. I haven't used this tool, but
the lead developer seems to like it. In my opinion, the format isn't as
nice as Javadoc's.

The URLs for these free tools are:

Javadoc Home Page: http://java.sun.com/products/jdk/javadoc/

dtd2html:
http://www.oac.uci.edu/indiv/ehood/perlSGML/doc/html/dtd2html.html

idldoc: http://herzberg.ca.sandia.gov/idldoc/


--
Anne Chenette
Technical Communication
e.Intelligence, Inc.
achenette -at- eintelligence-inc -dot- com

> From: "Regina Gilson" <regina -dot- gilson -at- tridion -dot- com>
>
> Dear TWers,
>
> I'm looking for personal accounts/opinions of tools that ease API
> documentation creation, such as DocJet by TallTree. Please send reviews of
> any tools you've used to create API docs.
>
> Thanks, Gina
>




Previous by Author: Re: Heuristics for Web Communication
Next by Author: Re: Technical writers who are also fiction writers
Previous by Thread: Re: Get to the point?
Next by Thread: API Documentation


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

Sponsored Ads


Sponsored Ads