DI-UMONS : Dépôt institutionnel de l’université de Mons

Recherche transversale
(titres de publication, de périodique et noms de colloque inclus)
2006-06-15 - Colloque/Présentation - communication orale - Anglais - 1 page(s)

Grosjean Philippe , "Collaborative writing of R documentation using a Wiki" in User!2006, Vienna, Austria, 2006

  • Codes CREF : Informatique générale (DI1162)
  • Unités de recherche UMONS : Ecologie numérique des milieux aquatiques (S807)
  • Instituts UMONS : Institut de Recherche sur les Systèmes Complexes (Complexys)
Texte intégral :

Abstract(s) :

(Anglais) Thanks to its Open Source license, R is developed by a large community of contributors. This makes a big part of the success of R, and also, it allows to propose a wide palette of additional functions in hundreds of R packages distributed on CRAN, Bioconductor, Omegahat, etc. Documentation (both for users and for developers) is an important component of any software. R proposes a couple of formats to standardize the way functions are documented: the Rd file, a LaTeX-like syntax that can be converted into different formats (using Rdconv), and the vignette, using Sweave to “compile” R code embedded in LaTeX document. Collaboration on writing these Rd files or vignettes is only possible by placing them in a CVS, or another similar collaboration system. There is no built-in collaboration tools in the R documents themselves. Currently, feedback about R documentation is done by sending bug reports (sic!), or by writing directly to the author(s) by email, thus, very basic and somehow inadequate ways to collaborate! There is also a large amount of documents (tutorials, manuals, reference cards, etc.) available on the web. A couple of web sites are really nice and propose interesting ways to share R code and R documentation, a good example being the R Graph Gallery (http://addictedtor.free.fr/graphiques/, by Romain François). Here again, there is little way to collaborate online on writing the documents: in the best situation, an author can submit a document to the server, and everybody has a read-only access to the page, once it is published. A Wiki is basically a web server where pages are editable by the readers directly in their web browser. Wiki pages use a very simple syntax that allows for easy formatting of even complex pages (for most advanced Wiki engines). One of the best example of what a Wiki can do is Wikipedia, with more than 992,250 articles (English version only) written and edited by a large community of volunteers. Wikipedia was recently compared to the well-known Encyclopedia Britannica by the scientific journal Nature, and it appeared that the quality of Wikipedia articles written by volunteers was equal to those written by paid experts in the Encyclopedia Britannica. This demonstrates the power of Wiki to write high-quality documentation is a collaborative way. There is a Wiki dedicated to R since a couple of years initiated by Detlef Steuer on http://fawn.unibw- hamburg.de/cgi-bin/Rwiki.pl. However, this Wiki has not grown as expected. We believe that it could be due to two main reasons: (1) not enough publicity about this site, and (2) the use of a simplistic Wiki engine that does not provide all R-specific features that would make R Wiki pages attractive (R code highlighting, direct link to the documentation for R functions and packages, etc.). We present here a new Wiki dedicated to R. The Wiki engine is based on DokuWiki, a power system targeting software documentation. This engine is modified and R-specific plugins are added to make it most suitable to edit R documentation. There are plugins for syntax highlighting of R code, for direct linking to the R functions documentation, or to the home page of R packages, etc.). As for the content, various authors have already accepted to move their documents to the new R Wiki: material from Detlef Steuer's Wiki, Paul Johnson's Rtips, Vincent Zoonekynd's Statistics with R, James Wettenhall's R tcltk examples, etc. The structure of the Wiki site has received much attention, and many people collaborated on making it clearer, easier, more efficient, initiating the really collaborative work around it (in alphabetic order: Jonathan Baron, Damian Betebenner, Roger Bivand, Ben Bolker, Patrick Burns, Nick Drew, Jose Claudio Faria, David Forrest, Romain François, Gabor Grothendieck, Frank Harrell, Paul Johnson, Martin Maechler, John Marsland, Duncan Murdoch, Tony Plate, Barry Rowlingson, Paul Sorenson, Detlef Steuer -sorry for those I forget to include in the list-). There is also a mailing list dedicate to this Wiki: 'r-sig-wiki' on https://stat.ethz.ch/mailman/listinfo/r-sig-wiki. The R Wiki is currently in the form of a prototype, but it will be available before June. The R-Core Team has decided to support one or several R Wiki initiatives, and the final version of this Wiki will probably be available through a simple URL like http://wiki.r-project.org or http://www.r-project.org/wiki. It will run on a dedicated server for maximum performance.