Re: [R] Documentation General Comments

From: seanpor <seanpor_at_acm.org>
Date: Wed, 23 Apr 2008 01:34:27 -0700 (PDT)

Good morning,

Firstly I'd like to say that I'm a huge fan of R and I think it's great system.

Part of the problem in searching for information is knowing what buzzwords / keywords to use. I was recently caught out like this as I didn't see my problem as a cumulative sum (keyword=cumsum) only as referencing one line of a dataframe from another. Academic papers and certain webpages add special classification keywords to the text of a page to help. Searching is a general problem - not just within R - ask any archivist or librarian!

A partial solution is to have disambiguation pages, e.g. http://en.wikipedia.org/wiki/Comma
Is it reasonable to have help pages with no specific R / package item behind it only a "See Also" section? Does somebody have access to the most frequent RSiteSearch() terms?

It would probably help to increase the number of "See Also" details - for example when I run into a problem the first thing I do is try to recreate it as a reproduceable toy problem which I could send to this list (which incidentally is actually a great way of figuring out solution to the problem without having to bother the list!!!). To do this I invariably want to generate some random numbers, and I can never remember the names runif() or rnorm() so I say help.search("random") which doesn't actually reference either runif() or rnorm() directly so I look at ?RNG which leads me to rnorm() - and already knowing that this is what I'm looking for I'm ok - but if somebody didn't already know this it is not obvious.

I appreciate that there is always a difficult balance when writing documentation between having enough and too much. Just looking at the core documentation for R-2.6.2 (and ignoring the many many additional packages) The introduction to R is 100 pages of PDF and the reference manual runs to 1,576 pages of PDF. Adding more information as many of us want would make the reference manual even more unwieldy and far too big to print out to peruse, which gives rise to a market for books which take over where the introduction manual leaves off...

Part of the difficulty that we encounter is that sometimes our difficulties are pure R, and other times the difficulty is statistical or mathematical - more often than not the problem is between the two... and frequently those of us asking the question don't actually know where on the spectrum it is...

Q: Could there be ways other than submitting a bug / patch to help improve R?

Q: Should this discussion be on r-devel or r-help?

Best Regards,
Sean

The root of the problem is that R is a voluntary/cooperative project and those who develop and maintain R are (generously) contributing their time and
probably have little-to-no time left over to devote to the improvement of the documentation.
<snip...>

This is why the documentation tends to be opaque in the first place. The people who build R are so clever and understand so much that they cannot put themselves in the shoes of those of us who are not so blessed with intelligence and erudition. So they (often) write terse cryptic instructions which (often) depend on background knowledge that many of us lack. That background knowledge can of course be found ***if you know where to look*** --- or even if you don't, given that you are prepared to put in sufficient time and effort searching ***and*** are clever at searching. It's that last requirement that leaves *me* out in the cold.

<snip...>

-- 
View this message in context: http://www.nabble.com/Documentation-General-Comments-tp16821085p16833353.html
Sent from the R help mailing list archive at Nabble.com.

______________________________________________
R-help_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Received on Wed 23 Apr 2008 - 08:49:10 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Wed 23 Apr 2008 - 09:30:30 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.

list of date sections of archive