RE: Intro to phases of creating API documentation

Subject: RE: Intro to phases of creating API documentation
From: "Sarah Stegall" <siliconwriter -at- comcast -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 8 Nov 2005 17:39:40 -0800


I do some 'post-processing'; I have to. We use doxygen rather than Javadoc,
but our output is similar: a website of linked HTML pages. In our case, some
of the code files are not part of the makefile (for excellent reasons I
won't go into here), and those comment files/APIs/headers must be added to
the collection. In addition, if I want to add my example code,
illustrations, overview, etc I must create those HTML pages and add them to
the collection.
The key is to make sure I *don't change any of the originally generated
documents*. I only add new ones and create a new navigation frame. When
developers generate a new set of documents, they all have the same file
names as before. I just copy all of the newly generated HTML files into the
website's folder, where they replace their obsolete predecessors without
disturbing the files or links I have created myself.

-----Original Message-----
From: bounce-techwr-l-184408 -at- lists -dot- techwr-l -dot- com
[mailto:bounce-techwr-l-184408 -at- lists -dot- techwr-l -dot- com] On Behalf Of Monica
Cellio
Sent: Tuesday, November 08, 2005 1:12 PM
To: TECHWR-L
Subject: Re: Intro to phases of creating API documentation

You should not do any post-processing of the javadoc output, because
it would just be lost the next time you build it anyway. In addition
to the class-level documentation, javadoc supports package overviews
and an overview of the whole doc set. Your developers might not have
written these; if they haven't you'll want to. This is how you turn
a package containing 20 classes (which will show up alphabetically)
in an API containing 500 classes (again, alphabetical) into something
navigable.



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

Try WebWorks ePublisher Pro for Word today! Smooth migration of legacy
RoboHelp content into your new Help systems. EContent Magazine Decision-
maker review (October 2005) is here: http://www.webworks.com/techwr-l

Doc-To-Help 2005 converts RoboHelp files with one click. Author with Word or any HTML editor. Visit our site to see a conversion demo movie and learn more. http://www.componentone.com/TECHWRL/DocToHelp2005

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



References:
Re: Intro to phases of creating API documentation: From: Monica Cellio

Previous by Author: Re: A prescriptive language?
Next by Author: RE: re native speakers
Previous by Thread: Re: Intro to phases of creating API documentation
Next by Thread: Re: Intro to phases of creating API documentation


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


Sponsored Ads