hi henrik (all): A better solution would be to have levels:
set.help(level="beginner"), which then provides expanded explanations.
However, I do not think this is necessary: For the most part, the online
R docs are great. It is not more detailed explanations that beginners
crave. My primary wishes arise as I stumble onto a need, and then wish
for a few more examples of different usage, a few more cross-references
to other functions, and the rare additional help page (exit, delete
(explains data frame row and col del), insert (same thing)). The first
two are usually literally one-liners, and unlikely to clutter up much.
The latter is pretty easy, too.
If considered helpful by the R developers, I would try to learn Rd to
submit doc changes. Alas, my feeling is that the reception would be
pretty cold ("not needed = redundant = no"). Is there someone
"in
charge of" docs that I can ask whether this is in principle welcome?
Would it be useful to add to the R Bug Report submission web page a
pulldown field that classifies suggestions, one of which being
"documentation enhancement", so that Prof Ripley won't complain
about
having to read these? Maybe another pull-down field that classifies
error severity?
regards, /iaw
Henrik Bengtsson wrote:
>Dear all,
>
>without taking sides here, I see two major advantage of keeping the
>redundancy in any documentation minimal. First, it makes the
>maintanance of the documentation as simple as possible. This in turn,
>minimizes the risk for getting inconsistent documentation in new
>updates. Otherwise, someone has to have a really good overview and
>know where to update when, say, one default argument is updated (or we
>have to live with incorrect documentation).
>
>One possible solution to a documentation for beginners is to have a
>separate package just for the documentation. In that package you can
>document ?exit etc . Load the package and help.search("exit") will
>find "anything" regard exitting. To get started with this you have
to
>know how to write Rd documentation (very similar to LaTeX). You'll
>find details in the help; type help.start().
>
>Cheers
>
>Henrik
>
>
>
>>-----Original Message-----
>>From: r-devel-bounces@stat.math.ethz.ch
>>[mailto:r-devel-bounces@stat.math.ethz.ch] On Behalf Of Gabor
>>Grothendieck
>>Sent: den 29 mars 2004 01:44
>>To: ivo.welch@yale.edu
>>Cc: R-bugs@biostat.ku.dk; r-devel@stat.math.ethz.ch
>>Subject: RE: [Rd] Help Documentation
>>
>>
>>
>>
>>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@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...
>>
>>______________________________________________
>>R-devel@stat.math.ethz.ch mailing list
>>https://www.stat.math.ethz.ch/mailma> n/listinfo/r-devel
>>
>>
>>
>>
>
>
>
