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]
