commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Al Chou <hotfusion...@yahoo.com>
Subject [math] where to cite references (was RE: cvs commit: jakarta-commons/math/src/java/org/apache/commons/math/stat/univariate/moment Kurtosis.java Skewness.java)
Date Mon, 05 Jul 2004 15:18:18 GMT
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 <phil@steitz.com> 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:mdiggory@latte.harvard.edu] 
> 	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:
> 	
> 	>--- psteitz@apache.org 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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message