Another FWIW comment since I'm not active on [math]. On Wed, 9 Jul 2003, Mark R. Diggory wrote:
> Date: Wed, 09 Jul 2003 14:31:32 -0400 > From: Mark R. Diggory <[EMAIL PROTECTED]> > Reply-To: Jakarta Commons Developers List <[EMAIL PROTECTED]> > To: Jakarta Commons Developers List <[EMAIL PROTECTED]> > Subject: [math] Userguide > > Just a thought (we've been around this subject before), I've often found > that when JavaDoc includes descriptive usage and examples that its > really promotes rapid understandng of the packages for me personally. I agree. > What are the current opinions on the following ideas? > > 1.) Javadoc = Userguide? Embed the userguide into the javadoc (though I > know we want to start playing with MathML in the userguide, I know we've > discussed issues with browser plugins and Javadoc generation that may > possibly complicate this subject) > Many commons packages build "user guide" sorts of documentation into the top level package.html or overview.html file that automatically gets included in the javadoc generation. Especially for things like class libraries (where the target audience of the user guide is a developer who also needs the API information anyway), Javadocs seems like a natural place for this -- plus, it's very easy to hyperlink from the user guide examples directly to the corresponding class or method documentation. > OR > > 2.) Use "crosslinks" throughout the Userguide and JavaDoc so they > reference each other at specific points of interest. > > -M. Craig > > -- > Mark Diggory > Software Developer > Harvard MIT Data Center > http://www.hmdc.harvard.edu > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
