[Rd] Help Documentation
Henrik Bengtsson
hb at maths.lth.se
Mon Mar 29 16:20:59 CEST 2004
Nothing to do with the topic, but before "reporting more bugs", maybe
this thread should stop sending Cc: to R-bugs at biostat.ku.dk. That's
why all messages show up twice (once with and once without "PR#nnnn"
in the subject). I did the same mistake earlier today.
Cheers
Henrik
> -----Original Message-----
> From: Liaw, Andy [mailto:andy_liaw at merck.com]
> Sent: den 29 mars 2004 16:13
> To: 'ivo welch'; Henrik Bengtsson
> Cc: R-bugs at biostat.ku.dk; r-devel at stat.math.ethz.ch
> Subject: RE: [Rd] Help Documentation
>
>
> Ivo,
>
> Let me address your points in reverse order:
>
> 1. There is a `wishlist' category for bug reports, which I
> guess you've overlooked.
>
> 2. There is also a `Contributed Documentation' section on the
> R web site, which you can submit your contribution. As well,
> there are a few introductory level documents there already
> that you might be interested.
>
> 3. I must repectfully disagree about adding/changing the help
> pages just so beginners or novices can learn R better. If
> the help pages are your sole source for learning R, I can
> only say that you could do a lot better. The help pages are
> supposed to be complete and accurate documentation of the
> topics they cover. The ones in R do a extremely good job at
> that, and, I must say, are much more user-friendly than most
> *nix man pages.
>
> If you had familiarize yourself with just the official newbie
> doc, `An Introduction to R', that would have solved most, if
> not all, of your questions. If you have not done that, there
> will be little enthusiasm to what you have to propose.
>
> Cheers,
> Andy
>
> > 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
> > 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 at stat.math.ethz.ch
> > >>[mailto:r-devel-bounces at stat.math.ethz.ch] On Behalf Of Gabor
> > >>Grothendieck
> > >>Sent: den 29 mars 2004 01:44
> > >>To: ivo.welch at yale.edu
> > >>Cc: R-bugs at biostat.ku.dk; r-devel at 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 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...
> > >>
> > >>______________________________________________
> > >>R-devel at stat.math.ethz.ch mailing list
> > >>https://www.stat.math.ethz.ch/mailma> n/listinfo/r-devel
> > >>
> > >>
> > >>
> > >>
> > >
> > >
> > >
> >
> > ______________________________________________
> > R-devel at stat.math.ethz.ch mailing list
> > https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
> >
> >
>
>
> --------------------------------------------------------------
> ----------------
> Notice: This e-mail message, together with any attachments,
> contains information of Merck & Co., Inc. (One Merck Drive,
> Whitehouse Station, New Jersey, USA 08889), and/or its
> affiliates (which may be known outside the United States as
> Merck Frosst, Merck Sharp & Dohme or MSD and in Japan, as
> Banyu) that may be confidential, proprietary copyrighted
> and/or legally privileged. It is intended solely for the use
> of the individual or entity named on this message. If you
> are not the intended recipient, and have received this
> message in error, please notify us immediately by reply
> e-mail and then delete it from your system.
> --------------------------------------------------------------
> ----------------
>
>
More information about the R-devel
mailing list