Wikis etc.

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Wikis etc.

Jack Tanner
Philippe's idea to start a wiki that grows out of the content on
http://zoonek2.free.fr/UNIX/48_R/all.html is really great. Here's why.

My hypothesis is that the basic reason that people ask questions on R-help
rather than first looking elsewhere is that looking elsewhere doesn't get
them the info they need.

People think in terms of the tasks they have to do. The documentation for R,
which can be very good, is organized in terms of the structure of R, its
functions. This mismatch -- people think of tasks, the documentation "thinks
in" functions -- causes people to turn to the mailing list.

What we need is documentation that can be browsed in terms of tasks, like
http://zoonek2.free.fr/UNIX/48_R/all.html. If that can be edited by the
community, all the better. This is especially good for newbies (like myself)
who try a tutorial, find that it lacks in some aspect, and can give
immediate feedback, e.g., via a Wiki.

As far as keeping current with the latest versions of R, I think we'll have
to arrive at some sort of convention that says: the code in this example
works with R version X, package version Y. Then, if that code is found to
fail in some future version, it's easy enough to make a second exampe. (As a
bonus, these examples could be an automated test suite for R.)

Philippe, if you find you'd like assistance, I'd like to help.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Michael Dewey
At 20:12 08/01/06, Jack Tanner wrote:

>Philippe's idea to start a wiki that grows out of the content on
>http://zoonek2.free.fr/UNIX/48_R/all.html is really great. Here's why.
>
>My hypothesis is that the basic reason that people ask questions on R-help
>rather than first looking elsewhere is that looking elsewhere doesn't get
>them the info they need.
>
>People think in terms of the tasks they have to do. The documentation for
>R, which can be very good, is organized in terms of the structure of R,
>its functions. This mismatch -- people think of tasks, the documentation
>"thinks in" functions -- causes people to turn to the mailing list.

Further to that I feel that (perhaps because they do not like to blow their
own trumpet too much) the authors of books on R do not stress how much most
questioners could gain by buying and reading at least one of the many books
on R. When I started I found the free documents useful but I made most
progress when I bought MASS. I do realise that liking books is a bit last
millennium.




Michael Dewey
http://www.aghmed.fsnet.co.uk

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Thomas Lumley
On Mon, 9 Jan 2006, Michael Dewey wrote:
>
> Further to that I feel that (perhaps because they do not like to blow their
> own trumpet too much) the authors of books on R do not stress how much most
> questioners could gain by buying and reading at least one of the many books
> on R. When I started I found the free documents useful but I made most
> progress when I bought MASS. I do realise that liking books is a bit last
> millennium.
>

Very late last millenium, though.
"When I were young[er] we didn't have all these fancy yellow books."

More seriously, yes, reading books about R and S is very effective and is
how most of the R experts learned.  In my case it was the Blue Book, the
White Book, and the Ripley/Venables/Smith notes on S-plus (which have
evolved to the Introduction to R).

  -thomas

"Ptolemy once asked [Euclid] if there was in geometry any shorter way that
that of the Elements, and he replied that there was no royal road to
geometry." Proclus (410-485 CE)

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Gabor Grothendieck
On 1/9/06, Thomas Lumley <[hidden email]> wrote:

> On Mon, 9 Jan 2006, Michael Dewey wrote:
> >
> > Further to that I feel that (perhaps because they do not like to blow their
> > own trumpet too much) the authors of books on R do not stress how much most
> > questioners could gain by buying and reading at least one of the many books
> > on R. When I started I found the free documents useful but I made most
> > progress when I bought MASS. I do realise that liking books is a bit last
> > millennium.
> >
>
> Very late last millenium, though.
> "When I were young[er] we didn't have all these fancy yellow books."
>
> More seriously, yes, reading books about R and S is very effective and is
> how most of the R experts learned.  In my case it was the Blue Book, the
> White Book, and the Ripley/Venables/Smith notes on S-plus (which have
> evolved to the Introduction to R).

In addition to books, the various manuals, contributed documents and
mailing list archives, all of which one should review,
the key thing to do if you want to really learn R is to read source code
and lots of it.  I think there is no other way.  Furthermore, the fact that
you can do this is really a key advantage of open source.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Leif Kirschenbaum-4
In reply to this post by Jack Tanner
To avoid spam on the R wikis pages:
  If we assume that anyone who we would want to be empowered to modify the R wiki pages is an R-user, would it be possible to somehow incorporate a function into the next R release which provides a user with a key/password?
  A new R function would generate a day-of-the year dependent key: if you want to modify an R wiki page you need to enter the key for that day (This is not a proposal to make keys user specific: every R user worldwide would have the same key each day). Then only a person who has installed R would be able to run the function to get a key to modify R wiki pages. Of course anyone could read the wikis.

I supposed that if we wanted, that the key provided could somehow encode the O/S and R version being run, and then the wiki page modified would note which O/S and version the annotator is running, however for ease of use I suggest that the key generated each day be short for simplicy in typing it in.

I suppose a more complex solution would be for an R function to make a call to open a web-browser with a cookie or something set which thus allows the user to modify R wiki pages.

Leif Kirschenbaum
Senior Yield Engineer
Reflectivity, Inc.
(408) 737-8100 x307
[hidden email]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

David Forrest
In reply to this post by Gabor Grothendieck
On Mon, 9 Jan 2006, Gabor Grothendieck wrote:

> On 1/9/06, Thomas Lumley <[hidden email]> wrote:
> > On Mon, 9 Jan 2006, Michael Dewey wrote:
> > >
> > > Further to that I feel that (perhaps because they do not like to blow their
> > > own trumpet too much) the authors of books on R do not stress how much most
> > > questioners could gain by buying and reading at least one of the many books
> > > on R. When I started I found the free documents useful but I made most
> > > progress when I bought MASS. I do realise that liking books is a bit last
> > > millennium.
> > >
> >
> > Very late last millenium, though.
> > "When I were young[er] we didn't have all these fancy yellow books."
> >
> > More seriously, yes, reading books about R and S is very effective and is
> > how most of the R experts learned.  In my case it was the Blue Book, the
> > White Book, and the Ripley/Venables/Smith notes on S-plus (which have
> > evolved to the Introduction to R).
>
> In addition to books, the various manuals, contributed documents and
> mailing list archives, all of which one should review,
> the key thing to do if you want to really learn R is to read source code
> and lots of it.  I think there is no other way.  Furthermore, the fact that
> you can do this is really a key advantage of open source.

There has to be some reason to dig into the source code.  Just starting at
line 1 and reading until you are enlightened would be frustrating,
repetetive, and nearly pointless.  The great benefits of the R books is
that they have interesting results (a fancy graph, analysis, or report)
that you can trace back to the constituent parts and (with open source
code) learn everything you want to and be confident that the rest is there
if you need it.  Books using R do an excellent job of showing what is
possible and, through recursive study of the open source code, how to do
it.  Books connect high-level tasks to low-level functions.

R has plenty of documentation, but if the measure of excellence is simply
number of pages or weight, SAS's documentation might still win even if we
include the pages of R source code.  Both packages have lots of detailed
documentation, where if you understood everything that was written, you'd
know how to do what you want.  The authors of neither R nor SAS have
failed to document their functions.

Where I think the R (and SAS) documentation is lacking is in the
connections between the documentation elements.  RTFM isn't helpful if you
can't find TFM.  For instance, there is more than one way to make a graph,
(see http://addictedtor.free.fr/graphiques/thumbs.php?sort=package for 135
of them) how does a novice know which function to use?  How do you find
out the alternate ways to do things?  The hateful MS Excel solves this by
registering the alternate graphic capabilities under a hierarchical GUI
menu.  We solve it with an email list and several fuzzy searches.

Since R has such an extensive set of extensions, maybe we need a section
in the R-intro documentation near
http://cran.r-project.org/doc/manuals/R-intro.html#Writing-your-own-functions
titled "Finding existing functions".  It could explain the difference
between base and recommended, installed, CRAN, and how someone can find
and use things in these areas using help(), '?', help.search(),
help.start(), RSiteSearch(), and the mailing lists.

Dave
--
 Dr. David Forrest
 [hidden email]                                    (804)684-7900w
 [hidden email]                             (804)642-0662h
                                   http://maplepark.com/~drf5n/

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Jack Tanner
In reply to this post by Michael Dewey
Michael Dewey wrote:

>At 20:12 08/01/06, Jack Tanner wrote:
>>My hypothesis is that the basic reason that people ask questions on R-help
>>rather than first looking elsewhere is that looking elsewhere doesn't get
>>them the info they need.
>>
>>People think in terms of the tasks they have to do. The documentation for
>>R, which can be very good, is organized in terms of the structure of R,
>>its functions. This mismatch -- people think of tasks, the documentation
>>"thinks in" functions -- causes people to turn to the mailing list.
>
>Further to that I feel that (perhaps because they do not like to blow their
>own trumpet too much) the authors of books on R do not stress how much most
>questioners could gain by buying and reading at least one of the many books
>on R. When I started I found the free documents useful but I made most
>progress when I bought MASS. I do realise that liking books is a bit last
>millennium.

I certainly agree about the value of books. After struggling with
lme/glmmPQL documentation for a while, I found a copy of MASS, and it's been
nothing short of illuminating.

Gabor Grothendieck <ggrothendieck <at> gmail.com> wrote:
>In addition to books, the various manuals, contributed documents and
>mailing list archives, all of which one should review,

I do not wish to disparage all these valuable resources. But it is apparent
that they do not answer the (real or perceived) needs of those who ask the
same more or less basic questions over and over on R-help. It doesn't help
if one, or ten, or hundreds of newbies are told -- go thee and RTFM,
because, by definition, there will be other "newbies" (presumably, until the
entire human race consists of R experts).

>the key thing to do if you want to really learn R is to read source code
>and lots of it.  I think there is no other way.  Furthermore, the fact that
>you can do this is really a key advantage of open source.

Absolutely, the R sources are the highest fidelity representation of the
knowledge on R. But there's also knowledge about the sources, e.g., why a
particular function was coded that way, and why one would want to use that
function over others that seem similar.

The wiki proposal is thus twofold: first, to take the key advantage of open
source, and apply it not only to the code, but to the knowledge about the
code as well. Second, to structure the experience of learning and using R
such that the wiki is very prominent.

Unfortunately, the site is down at the moment, but there's a really good
example of how wikified, task-oriented documentation can help an open source
project: http://codex.wordpress.org/Main_Page .

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Gabor Grothendieck
On 1/9/06, Jack Tanner <[hidden email]> wrote:

> Michael Dewey wrote:
> >At 20:12 08/01/06, Jack Tanner wrote:
> >>My hypothesis is that the basic reason that people ask questions on R-help
> >>rather than first looking elsewhere is that looking elsewhere doesn't get
> >>them the info they need.
> >>
> >>People think in terms of the tasks they have to do. The documentation for
> >>R, which can be very good, is organized in terms of the structure of R,
> >>its functions. This mismatch -- people think of tasks, the documentation
> >>"thinks in" functions -- causes people to turn to the mailing list.
> >
> >Further to that I feel that (perhaps because they do not like to blow their
> >own trumpet too much) the authors of books on R do not stress how much most
> >questioners could gain by buying and reading at least one of the many books
> >on R. When I started I found the free documents useful but I made most
> >progress when I bought MASS. I do realise that liking books is a bit last
> >millennium.
>
> I certainly agree about the value of books. After struggling with
> lme/glmmPQL documentation for a while, I found a copy of MASS, and it's been
> nothing short of illuminating.
>
> Gabor Grothendieck <ggrothendieck <at> gmail.com> wrote:
> >In addition to books, the various manuals, contributed documents and
> >mailing list archives, all of which one should review,
>
> I do not wish to disparage all these valuable resources. But it is apparent
> that they do not answer the (real or perceived) needs of those who ask the
> same more or less basic questions over and over on R-help. It doesn't help
> if one, or ten, or hundreds of newbies are told -- go thee and RTFM,
> because, by definition, there will be other "newbies" (presumably, until the
> entire human race consists of R experts).

I certainly was not disparaging books.  I said _in addition to_ books,
not _insted of_.  The reason I pointed this out is that I think
most people already read the books.  What many people don't
do as far as can tell is read the code.  Obviously if you are just
starting out you are going to be relying on the documentation,
books, etc. but once you get past the intro stage you need to get
into code.  One repeatedly sees questions on this list where just
a minute or two spent with the code would have answered the
question.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

JohnDee
On Monday 09 January 2006 11:31, Gabor Grothendieck wrote:

> . . .
>
> I certainly was not disparaging books.  I said _in addition to_ books,
> not _insted of_.  The reason I pointed this out is that I think
> most people already read the books.  What many people don't
> do as far as can tell is read the code.  Obviously if you are just
> starting out you are going to be relying on the documentation,
> books, etc. but once you get past the intro stage you need to get
> into code.  One repeatedly sees questions on this list where just
> a minute or two spent with the code would have answered the
> question.
>
Gabor,  

The issue IS the INTRO stage though, in fact well beyond the intro stage.  
Reading the code is well and good for a programmer, but many are not and
never will be coders, and this group is going to continue to expand.  Even an
advanced statistician migrating from a proprietary system like SPSS to R is
going to need documentation.  They would not even know where in the code to
look!  Code is cool, but it really isn't expository.

John

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Wikis etc.

Michael Dewey
In reply to this post by Gabor Grothendieck
At 16:06 09/01/06, Gabor Grothendieck wrote:

[snip various earlier posts]


>In addition to books, the various manuals, contributed documents and
>mailing list archives, all of which one should review,
>the key thing to do if you want to really learn R is to read source code
>and lots of it.  I think there is no other way.  Furthermore, the fact that
>you can do this is really a key advantage of open source.

But that is the solution to a different problem.
Reading the source for merge tells you how R merges two dataframes, the
beginning user wants to know how to link together the information s/he has
in two files but does not know what the name of the relevant command is, or
indeed whether it is even possible.

To give you some idea of how ignorant some of us are it was only quite
recently that I realised (despite several years reading free documentation,
books on R and R-help) that if I type cor at the prompt what I see looks
like source code but is not _the_ source code.


Michael Dewey
http://www.aghmed.fsnet.co.uk

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Improving R-Intro {was "Wikis etc."}

Martin Maechler
In reply to this post by David Forrest
>>>>> "David" == David Forrest <[hidden email]>
>>>>>     on Mon, 9 Jan 2006 11:54:30 -0600 (CST) writes:

          ..................
          ..................


    David> Since R has such an extensive set of extensions,
    David> maybe we need a section in the R-intro documentation
    David> near

    David> http://cran.r-project.org/doc/manuals/R-intro.html#Writing-your-own-functions
    David> titled "Finding existing functions".  It could
    David> explain the difference between base and recommended,
    David> installed, CRAN, and how someone can find and use
    David> things in these areas using help(), '?',
    David> help.search(), help.start(), RSiteSearch(), and the
    David> mailing lists.

That's a good suggestion.
The file to improve is the texinfo source file (the *.html is
produced from it, as well as the *.pdf version of the manual),
is always available from the subversion archive (as all the rest of
the R sources, past and present), the intro manual being
  https://svn.r-project.org/R/trunk/doc/manual/R-intro.texi

So, yes, we'd welcome (a patch against / an improved version of)
the above file!

Martin

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html
Reply | Threaded
Open this post in threaded view
|

Re: Improving R-Intro {was "Wikis etc."}

Brett Magill
On an improved R wiki, R-intro:

I think the issue of user-friendliness of documentation has been raised.
  When I first started using R, I found the S-PLUS online documentation
very useful.  It is very user-friendly and a great introduction,
organized by application. See:

S-PLUS 6 Guide to Statistics, Volume I
S-PLUS 6 Guide to Statistics, Volume II

at http://www.insightful.com/support/doc_splus_win.asp

How about a wiki based on this as a model, with some preliminaries and
then user additions.  Of course, the bottom line is, we need something
targeted at end-users, not developers.

Brett

Martin Maechler wrote:

> That's a good suggestion.
> The file to improve is the texinfo source file (the *.html is
> produced from it, as well as the *.pdf version of the manual),
> is always available from the subversion archive (as all the rest of
> the R sources, past and present), the intro manual being
>   https://svn.r-project.org/R/trunk/doc/manual/R-intro.texi
>
> So, yes, we'd welcome (a patch against / an improved version of)
> the above file!
>
> Martin

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide! http://www.R-project.org/posting-guide.html