[R] a proposal regarding documentation

[Philippe Grosjean]

John Sorkin wrote:
> Perhaps help pages should have links to relevant portions of the WIKI.
> John      
> 
> John David Sorkin M.D., Ph.D.
> Chief, Biostatistics and Informatics
> University of Maryland School of Medicine Division of Gerontology
> Baltimore VA Medical Center
> 10 North Greene Street
> GRECC (BT/18/GR)
> Baltimore, MD 21201-1524
> (Phone) 410-605-7119
> (Fax) 410-605-7913 (Please call phone number above prior to faxing)
> 
>>>> spencerg <spencer.graves at prodsyse.com> 6/14/2009 1:53 PM >>>
> The documentation for the "nlme" package was improved a few years 
> ago by an informal process of this nature.  When I first started 
> following r-help, I answered many questions suggesting in part the the 
> person read some portion of Pinheiro and Bates (2000).  At that time, 
> none of the help pages mentioned Pinheiro and Bates, because they were 
> completed before the book and had not been updated.  Eventually, I 
> volunteered to add that to some of the help pages.  Doug agreed.  In the 
> process, I also expanded some of the examples and modified the text in 
> places where I thought I could make it more easily understood. 
> 
> 
>       One obvious way to do this would be to provide write access to the 
> main R subversion repository.  However, that likely would not be 
> acceptable to the R-core team unless it were limited to a very few 
> individuals they already knew and trusted, and those individuals could 
> process suggestions from others.  As mentioned, there would need to be 
> additional ground rules.  For example, an inappropriate example might 
> cause "R CMD check" to fail on some platforms but not others.  This 
> could expose problems with the core code, which perhaps should be fixed 
> but not necessarily in the time frame desired by this new documentation 
> improvement team.  For a second example, Brian Ripley once rejected a 
> suggested change to a help page because it referred to a package outside 
> the core R code. 
> 
> 
>       A less threatening alternative might be to direct this energy into 
> improving the R Wiki.  I have contributed to other Wiki projects, and 
> I've found them to be quite useful and dynamic.  The current R Wiki has 
> not so far lived up to its potential.  However, I believe that is just a 
> matter of building a critical mass of R Wiki contributors.  Many 
> questions on R help could best be answers by first cheking and perhaps 
> improving the R Wiki and then directing the questioner to the Wiki.  I 
> plan to do that "sometime", but not yet. 
> 
> 
>       Hope this helps. 
>       Spencer Graves

I agree. The R Wiki probably needs these steps:
1) To reorganize its general structure in order to find more easily 
relevant pages,

2) To rework the engine, and in particular the main page template to 
make it easier and more intuitive for R users,

3) ... most importantly: to move it to a faster server, so that it will 
be more responsive, and

4) To build a RWiki package with functions to ease access of the wiki 
pages (direct search in the wiki, retrieve code in R from a given wiki 
page, etc.). I have started something in this direction, but currently 
lack time to finalize it.

Finally, the most important aspect is to get a group of volunteers to 
move and reformat nice discussions from R-Help/R-Devel/R-SIG-whatever 
into refined wiki pages... and with a referee mechanism to double/triple 
check content on the wiki. This happens erratically and certainly lacks 
proof-checking and feedback to the corresponding mailing list.

Beside this, I am completely open to suggestions.

Interested people could contact me directly. We could certainly arrange 
a dinner in Rennes at User!2009 to discuss evolution of the R Wiki, in 
particular, targeting collaborative writing of *good quality* documentation.

Best,

Philippe Grosjean

> [...]