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

Martin Maechler maechler at stat.math.ethz.ch
Mon Apr 24 08:33:59 CEST 2006


>>>>> "Gabor" == Gabor Grothendieck <ggrothendieck at gmail.com>
>>>>>     on Sun, 23 Apr 2006 09:43:07 -0400 writes:

    Gabor> I think the most important thing is that if you click
    Gabor> on tips in the left hand pane that you get to the
    Gabor> table of contents discussed here rather than the
    Gabor> uninformative one.  It should not be necessary to
    Gabor> read the page at all whether it uses folding or not.

I agree with Gabor:
Philippe, maybe you and I (to some extent) belong to the small
and diminishing (up to extinction) part of the population who do
read and even like to read and do this even with web pages (and
R help pages!)
The vast (and growing) majority of the population are *scanning*
web pages until they've found something that seems somewhat
relevant and is "clickable"...

And, I have to admit that indeed, the scanning strategy is
often more effective than the reading one..
Martin

    Gabor> On 4/23/06, Philippe Grosjean
    Gabor> <phgrosjean at sciviews.org> wrote:
    >> Gabor Grothendieck wrote: > Its too much to expect that
    >> people are going to read everything that is > there.
    >> They just want to get to where they are going as fast as
    >> possible > and to read the entire page and then figure
    >> out you have to click on the > word shorter is subtle,
    >> complicated and time consuming.
    >> 
    >> Not my fault! The start page I proposed was one screen
    >> height, with only five links (one for each main section
    >> in the Wiki), and less that 50 words in total. So, quick
    >> to read, easy to spot where to go, etc. But them, many
    >> people told me that this starting page was rather
    >> uninformative and that one needed more about what is
    >> inside each section... so, this is done! And yes, this
    >> necessarily dilutes content.
    >> 
    >> As a betgter compromize, I intend to rework that start
    >> page using folded sections that you can unfold by
    >> clicking on them. So, the first presentation will be
    >> similar to my original page, with the possibility to get
    >> more details right on this starting page.
    >> 
    >> PhG
    >> 
    >> > To make it > doubly confusing if you do click on tips
    >> to the left you get to something > so there is no reason
    >> to suspect that there is a better alternative.
    >> >
    >> > On 4/23/06, Philippe Grosjean <phgrosjean at sciviews.org>
    >> wrote:
    >> >
    >> >>Gabor Grothendieck wrote:
    >> >>
    >> >>>Yes, possibly with some elaboration in certain cases.
    >> By the way, >>>that is not the page you get if you click
    >> on tips after going to >>>wiki.r-project.org and clicking
    >> on tips to the left.
    >> >>
    >> >>How many times do I need to tell that the left pane
    >> displays, by >>default, the complete index of all wiki
    >> pages, but this will be replaced >>by more useful
    >> 'sidebars'. We haven't done these sidebars yet. So, this
    >> >>part of the site must still be considered as work in
    >> progress.
    >> >>
    >> >>Now, here is what happens when you navigate through
    >> pages: >>1) You enter in http://wiki.r-project.org,
    >> right?
    >> >>
    >> >>2) You read this page (considering you are visiting the
    >> site the first >>time... otherwise, you would have
    >> bookmarked 'tips:tips', I suppose) and >>see:
    >> >>
    >> >>...
    >> >>
    >> >>Tips & Tricks
    >> >>
    >> >>A large compendium of _shorter pages_ describing
    >> details of how >>particular commands can be used and
    >> giving examples of useful code.  >>...
    >> >>
    >> >>with "shorter pages" being a link pointing to that
    >> 'tips:tips' page. So, >>what simpler can I do?
    >> >>
    >> >>PhG
    >> >>
    >> >>
    >> >>
    >> >>>On 4/23/06, Philippe Grosjean
    >> <phgrosjean at sciviews.org> wrote:
    >> >>>
    >> >>>
    >> >>>>Gabor Grothendieck wrote:
    >> >>>>
    >> >>>>
    >> >>>>>In thinking about this some more perhaps one
    >> possibliity would be to have >>>>>an index which
    >> incluldes the answer.  That would allow one to browse the
    >> >>>>>key code and also see an expanded wiki discussion.
    >> >>>>>
    >> >>>>>e.g.
    >> >>>>>
    >> >>>>>1.1 Bring raw numbers into R: scan(myfile) >>>>>1.2
    >> Basic notation on data access: iris[1,2] >>>>>1.3
    >> Exchange data between R and Excel/other progs:
    >> read.xls(excelfile) >>>>>[also robdc, foreign and Hmisc
    >> packages] >>>>>1.4 Merge data frames: merge(ds1, ds1, by
    >> = c("city", "x1"),all=TRUE)
    >> >>>>
    >> >>>>Hum, hum... you mean, something like:
    >> >>>>http://wiki.r-project.org/rwiki/doku.php?id=tips:tips
    >> >>>>
    >> >>>>:-)
    >> >>>>
    >> >>>>PhG
    >> >>>>
    >> >>>>
    >> >>>>
    >> >>>>
    >> >>>>>On 4/23/06, Gabor Grothendieck
    >> <ggrothendieck at gmail.com> wrote:
    >> >>>>>
    >> >>>>>
    >> >>>>>
    >> >>>>>>Each tip should be one (or a small number of lines)
    >> for the description >>>>>>and one line (or a small number
    >> of lines) for the answer -- not pages.  >>>>>>Look at
    >> Paul Johnson's original organization and its quite clear
    >> its >>>>>>superior for both browsing and searching.
    >> >>>>>>
    >> >>>>>>On 4/23/06, Gavin Simpson <gavin.simpson at ucl.ac.uk>
    >> wrote:
    >> >>>>>>
    >> >>>>>>
    >> >>>>>>
    >> >>>>>>>On Sun, 2006-04-23 at 05:57 -0400, Gabor
    >> Grothendieck wrote:
    >> >>>>>>>
    >> >>>>>>>
    >> >>>>>>>
    >> >>>>>>>>On 4/23/06, Philippe Grosjean
    >> <phgrosjean at sciviews.org> wrote:
    >> >>>>>>>>
    >> >>>>>>>>
    >> >>>>>>>>
    >> >>>>>>>>>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
    >> i
    >> >>>>>>
    >> >>>>>>ndex, 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!
    >> >>>>>>>>>
    >> >>>>>>>>
    >> >>>>>>>>You want to browse the code itself, not just an
    >> index.  The way >>>>>>>>you learn R is to look at a lot
    >> of code and not by having to waste >>>>>>>>time jumping
    >> to dozens or hundreds of different pages.
    >> >>>>>>>
    >> >>>>>>>Gabor
    >> >>>>>>>
    >> >>>>>>>/you/ might learn R best that way, but I doubt
    >> many people will. From my >>>>>>>own experience and from
    >> teaching R to colleagues and with students on
    >> >>>>>>>short courses is that they like a reasonable
    >> grounding in the basics to >>>>>>>allow them to get
    >> started, and then when they started doing their own
    >> >>>>>>>thing they want to ask "how do I do x?" Scanning a
    >> list of tips allows >>>>>>>them to drill down to the few
    >> items that sound like they might answer >>>>>>>their
    >> question. People don't want to read page after page of
    >> code - >>>>>>>especially on a screen - just to find the
    >> one sentence or line of code >>>>>>>that will help them
    >> solve their immediate problem.
    >> >>>>>>>
    >> >>>>>>>G



More information about the R-sig-wiki mailing list