The issue is one of referential integrity. Say we release javadoc for version 1.0 and have user doc on the math site that it links to. Then (lets say) we update the doc on the site such that a page is removed. Now there are versions of the javadoc out in the wild that point to a dead link. So, linking in such a way is very restrictive to our being able to update the user guide.
Now, I think the user guide is not that large that it couldn't be distributed on combination with the javadoc, then the javadoc references could be based on relative linking to the local copy of the userdoc.
Ultimately we are trying to resolve the fact that we can't use xdoc in such a way as to embed it into javadoc directly. Would we even want to?! I think its best if we maintain a parallel xdoc structure to the javadoc package structure and distribute them together as one package that is relatively linked. This really just means packaging up portions of the site docs such that they are expanded from the tar file and that they can still be navigated in the local file system in a browser
-Mark
Al Chou wrote:
I rather prefer hyperlinks in the Javadoc as well. I don't see why it should be brittle to link from the Javadoc to the user guide -- it's not as if we're frequently changing the list of references. The fact that the user guide is online at the project site should help us keep it up to date (it's visible to the public, which always gives me more incentive to do the right thing <g>).
One thing that occurs to me as I look at the [math] site: like other Apache
project sites, it's not immediately obvious from the navigation menu (or any
other part of the home page) how one should submit feedback about the project. Sure, there are several links that sound promising (e.g., About Us >
Contributors, General Information > Contributing Patches, Jakarta Community >
Mailing Lists), but these typically point to Jakarta Commons in general rather
than Commons-Math specifically (I realize that may be because we're using a
Commons template to generate the page), but no obvious "submit a bug report",
"submit feedback", "request support", "ask a question" sort of feature. Users
have to be rather motivated to discover a way to send us a message (most likely
Project Documentation > Issue Tracking), and I think the project is probably
the poorer for it, as many users aren't nearly motivated enough to dig in that
far (the company where I work develops a product that helps address that and
many other related issues with Web sites/apps).
On a different note, I'm not current on how the Commons-Math site is generated; I have a vague memory that Mark's been initiating that process manually. Is there a strong reason the nightly build shouldn't do it? Some of the content seems a little (a few weeks, as opposed to months) out of date, such as the TODO list, which Phil, Mark, and Brent have diligently been working through (apologies to any whom I forgot to mention).
Al
--- Phil Steitz <[EMAIL PROTECTED]> wrote:
I would prefer to keep the references that we actually need in the javadoc itself. The ones that I removed were just references to (standard, straightforward) definitions, which I had added inline. In general, I want to include definitions in the javadoc unless this is not tractable (too many dependent concepts, formulas too complex, etc.), in which case a reference to a definitive source should be included. When we use algorithms that are not elementary or widely known, we should include references to docs or papers (e.g. the Chan et al references for the moment updating formulas).
Unfortunately, the first sentence above is a PITA to maintain and leaves us open to broken links (last time I rank linkcheck, the p-value reference was broken :-( That makes suggestions like Mark's appealing, but I don't like losing the hyperlinks. Is it excessively brittle to include links from the javadoc back to the user guide? If so, is there any stable place (better than ~psteitz) where I can host some definitions?
Phil
-----Original Message----- From: Mark R. Diggory [mailto:[EMAIL PROTECTED] Sent: Fri 7/2/2004 8:51 AM To: Jakarta Commons Developers List
Subject: Re: cvs commit:
jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment
Kurtosis.java Skewness.java
What if we maintained "Citation Numbers" in the javadoc and then
maintained references to external sources in the Math Site documentation?
Al Chou wrote:
>--- [EMAIL PROTECTED] wrote:
> >
>>psteitz 2004/07/01 22:29:14
>>
>> Modified: math/src/java/org/apache/commons/math/stat/univariate/moment
>> Kurtosis.java Skewness.java
>> Log:
>> Removed link to external definition, as formula has been added to
javadoc.
>
>Maybe it's my grad school experiences talking, but I would prefer to retain
>links to external references. That way if a user (or even one of us
>developers) ever needs to look up the original references, its easy to do,
and
>there's an explicit statement of which source of information we used,
rather
>than doing a Web search and wondering which (if any) of the resulting
resources
>was the original reference. Maybe that doesn't matter to anyone but me?
>
>
>Al
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
-- 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]
