You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by "Mark R. Diggory" <md...@latte.harvard.edu> on 2003/07/09 20:31:32 UTC
[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.
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)
OR
2.) Use "crosslinks" throughout the Userguide and JavaDoc so they
reference each other at specific points of interest.
-M.
--
Mark Diggory
Software Developer
Harvard MIT Data Center
http://www.hmdc.harvard.edu
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Userguide
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Mark R. Diggory wrote:
> 1.) Javadoc = Userguide?
Hmm, depends on what scopes "user guide" should cover:
- Reference view: usually JavaDoc only
- Use cases, task oriented view: Can be put into class JavaDoc
or package.html but a structure orthogonal to the
packages/classes would probably be useful.
- Task/usecase index and cross reference: separate, could be a
set of topic maps.
- Tutorial, step-by-step introduction: overview.html but a
separate document is usually warranted. I'm unsure whether
this is relevant to [math].
- Term definitions, nomenclature, glossary, bibliography: Can
be in package.html or overview.html, but should probably be
separate.
> 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)
Render the MathML into SVG or/and Bitmaps and provide them as fallback.
J.Pietschmann
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [math] Userguide
Posted by "Craig R. McClanahan" <cr...@apache.org>.
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 <md...@latte.harvard.edu>
> Reply-To: Jakarta Commons Developers List <co...@jakarta.apache.org>
> To: Jakarta Commons Developers List <co...@jakarta.apache.org>
> 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: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org