[R] Documentation General Comments

[seanpor]

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.