[R] suggesting documentation (was paired t-test vs pairwise t-test)

[Prof Brian Ripley]

On Fri, 20 Aug 2004, John Christie wrote:

> On Aug 20, 2004, at 6:16 PM, Berton Gunter wrote:
> 
> > The fact is that, while certainly desirable,  it is very difficult and
> > time-consuming to write the sort of extensively exampled, 
> > instructional Help
> > files that you desire.
> 
> It would be great if one could easily submit a modified help file for 
> inclusion in the default distribution.

You can (for _consideration_ for inclusion, that is).  You send a report
to R-bugs of a documentation problem with either a patch or a complete new
.Rd file.

*However* if we are going to start having help files which attempt to
teach statistics we will need an expert moderator to review them and that
will slow (or even halt) their takeup.  That's not to discourage people
suggesting factual information, in this case a description of the class
"pairwise.htest" and some references.

BTW, at least this help page does describe the value: many do not.

>   In fact, maybe we could review them on the mailing list and they could
> be submitted with subjects like "proposed help for pairwise.t.test" or
> some such.  Then the community could also do the editing and the
> discourse would be available for search.

Not on _this_ mailing list, please (this would be better on R-devel, and
most likely this would need a separate mailing list again).  And please
keep the subject line in track with the subject, folks.

> Maybe I'm missing something but I don't see an easy way to help with 
> this ad hoc.  Perhaps someone (hey, maybe me) could volunteer as a 
> filter for ad hoc help modifications.  Although, I certainly do not 
> feel qualified.

See above.

Behavioural psychology does come into this.  This thread has been
extremely discouraging to those few of us who do work on the
documentation.  Since this it seems unappreciated (and some of the
comments have been a good deal less than appreciative), it will go further
down the list of enjoyable tasks to do for R.  Do remember R is a
volunteer project and the volunteers are in the audience.

Finally, a radical suggestion.  Many respondents are from commercial 
addresses.  Perhaps a group of you would like to put forward a proposal to 
the R Foundation to sponsor an R documentation project.

BDR

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595