From: ivo welch
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
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
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
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
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
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...