[R-wiki] Gelman's comments about R tips vs Wiki

Philippe Grosjean phgrosjean at sciviews.org
Sun Apr 23 09:56:15 CEST 2006

Tony Plate wrote:
 > [...] (see hereunder for full post)
 > However, maybe this can be partially addressed by having larger index
 > pages, each one pointing to many different small example pages. [...]

Exactly! Speaking about "browsing" the tips, the key is not to have all 
tips on one page, but an index, table of content, summary, or 
whatever-you-call-it page. You browse that page and click on the links 
you want. This is more effective than browsing tens of thousands of 
lines to discover that the tips you are looking for is the forelast one, 
that is, the 9,999th one!

It seems that it would be good to (re)read 
http://wiki.r-project.org/rwiki/doku.php?id=wiki:authoring, the Wiki 
authoring guide:


=== Can I compile my own table of content? ===


     I want to collate together a series of Wiki pages by creating an 
original table of content. I want to do this to prepare a course or a 
tutorial targetting a specific audience. I don’t want to write that 
document from scratch, and I think that a couple of R Wiki pages just 
correspond to what I need. Can I do that?

Answer: Yes, you can. All material on the R Wiki is licensed under the 
Creative Commons Attribution-NonCommercial-ShareAlike License Version 
2.5. This means that you can collect material together providing: (1) 
you indicate respective authors, (2) this is not intended for commercial 
use, and (3) you compilation is redistributed under a similar license.

There are three ways to collect together Wiki pages:

    1. Export the pages of interest as XHTML, by appending 
&do=export_xhtml at the end of the URL and reload it. You can copy and 
paste the page(s) either in your favorite HTML editor, or in a word 
processor like OpenOffice Writer or Microsoft Word (do not forget to 
point to the R Wiki as the origin of the material).

    2. Link to the pages of interest from your own Web or Wiki site.

    3. But if you think your table of content could be interesting for 
other R users, please, share it by adding it directly into this R Wiki.

Those who want to provide a tool to automate the collation of several 
Wiki pages and compile an unique PDF file are warmly welcome to 
contribute. However, I think it is, in all cases, much better to work 
only with the original pages on the Wiki. A leading concept of the Wiki 
is to stimulate every reader to become an author. This is easy to do 
when you read the original Wiki page (just click 'Edit this page' on the 
top or bottom left of the page). For sure, readers of the PDF version 
are less likely to contribute, since the access to the editable Wiki 
page is not straightforward for them (and they may even not know that 
there is a Wiki equivalent of the PDF)!

To conclude, I think that many proposals these times are done by people 
that do not like the Wiki presentation and would prefer a Web or PDF 
presentation. The later two are incompatible with the leading idea of 
the Wiki that every reader can easily become an author. Applying the 
proposed changes to the Wiki will certainly lead to a more "Webish" or 
"PDFish" look&feel of R Wiki, but it will almost certainly break the 
initial idea of a place for *collaboratiove writing of R documentation*.

Philippe Grosjean

Tony Plate wrote:
> My feeling too is that having more on a single page makes for much 
> easier browsing when you don't know exactly what you're looking for, or 
> when the terminology is unfamiliar (both of which are likely to be true 
> for many users of the Wiki).
> However, maybe this can be partially addressed by having larger index 
> pages, each one pointing to many different small example pages.  I'm not 
> sure how well this could work.  If each example could be concisely 
> described in a few words it might work well (then those few words could 
> be used on the index page).
> -- Tony Plate
> Gabor Grothendieck wrote:
>> On 4/21/06, Philippe Grosjean <phgrosjean at sciviews.org> wrote:
>>> Hi,
>>> Although I am ready to consider your point of view, I think I don't
>>> understand it very well.
>>> 1) Rtips is, by definition, a collection of short R code snippets. They
>>> are, of course, collected together in a logical way (i.e., sections with
>>> tips dealing with similar topics). Now, *why the hell would you like to
>>> have a linear presentation of these tips???* (is this what you mean by:
>>> "the nonlinearity of hyperlinks just adds confusion." ?) The best way to
>>> access these tips is by looking at keywords (the search box) and reading
>>> the tips related to your particular problem.
>> The best way is to browse, not search, since its hard to know exactly
>> what one wants.  If its all on one page or a small number of pages 
>> then its
>> easy to do but if one has to search for it it makes it much harder. I
>> would therefore agree with the posters who indicated that the original
>> one page Rtips was a superior organization.
>> One idea is to have it on one or a small number of Wiki pages and have 
>> a program
>> that collects them altogether in a document that can be downloaded.  That
>> program could be run periodically to provide a snapshot, e.g. once a week
>> or once a month.
>> _______________________________________________
>> R-sig-wiki mailing list
>> R-sig-wiki at r-project.org
>> https://stat.ethz.ch/mailman/listinfo/r-sig-wiki

More information about the R-sig-wiki mailing list