[Rd] R-bugs is for BUGS (was Help Documentation (PR#6717))

Thomas Lumley tlumley at u.washington.edu
Mon Mar 29 16:41:20 CEST 2004 

Everyone,

While this has been in some ways a useful discussion, the most important
part of Brian's initial complaint was that the messages were sent to
R-bugs.  All this follow-up discussion has *also* been sent to R-bugs,
often by people who know better.

If it isn't a bug report, *don't send it to R-bugs.*

	-thomas


On Mon, 29 Mar 2004 andy_liaw at merck.com wrote:

> 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
> >
> >
>
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
>

Thomas Lumley			Assoc. Professor, Biostatistics
tlumley at u.washington.edu	University of Washington, Seattle

More information about the R-devel mailing list