[Rd] Help Documentation (PR#6714)

[ggrothendieck at myway.com]

I think many people share your view and are aghast at the
reception that some well-intentioned posts receive.  There 
have been past discussions on this and many people feel the
way you and I do.  

Just to head off another round, let me acknowledge that 
there appears to be multiple viewpoints and although hard 
to believe by myself, there actually is a contingent that 
views what I see as insulting responses as appropriate.

---
From:   ivo welch <ivo.welch at yale.edu>

ladies and gents:

I have posted a couple of simple questions recently. As often happens 
to novices, the information was there somewhere, even in front of my 
eyes, and I just did not see it. I looked in docs that seemed to me to 
be the right place for this particular information, but did not find it. 
There is no question: mea culpa, and everything is documented somewhere 
in R. (Worst comes to worst, it is documented in the source.)

But here comes my complaint: I tried to help by documenting where I got 
lost, and by suggesting simple one-liners for the documentation, which 
would provide additional cross-references to what I was looking for. 
The cost of adding additional brief sentences to the help must be 
relatively small, and the help to stuck novices may be considerable in 
reducing the learning curve. For my specific examples, I suggested a 
reference to q() in ?exit, and a "select= -c(v1,v2)" to ?subset.

Clearly, the information is redundant. (Of course, in a sense, all 
documentation is redundant.) The goal of good documentation should be 
to help novice users who do not know the answer. The goal should not be 
minimum redundancy in the help files. Being fairly new to R, I see 
difficulties where Brian Ripley and other experts and developers no 
longer do. I bet that if I wonder about the answers, I am more than 
likely not alone. In fact, I think it would really make sense to 
improve the docs by studying where novices get stuck.

I was told by Brian to stop sending such suggestions, in order not to 
clutter the R bug report list. OK, I can save my time; I just wanted to 
help. But, for others' sake, please reconsider the policy of not 
gearing the internal R documentation for novices like myself.

I will butt out here.

regards,

/ivo

PS: Incidentally, the R help seems a little schizophrenic. For 
example, Brian Ripley is the most helpful source for learning R (both 
books and posts), and I am rather grateful for it. I just do not 
understand why, at the same time, he seems to be annoyed while fielding 
questions of the r-help post-list. He is not the only individual who 
likes to help, but grudgingly so...