From hb at maths.lth.se  Mon Mar 29 16:20:59 2004
From: hb at maths.lth.se (Henrik Bengtsson)
Date: Mon Mar 29 16:21:08 2004
Subject: [Rd] Help Documentation
In-Reply-To: <3A822319EB35174CA3714066D590DCD504AF7AB5@usrymx25.merck.com>
Message-ID: <000101c41599$0f0c4b20$e502eb82@maths.lth.se>

Nothing to do with the topic, but before "reporting more bugs", maybe
this thread should stop sending Cc: to R-bugs@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@merck.com] 
> Sent: den 29 mars 2004 16:13
> To: 'ivo welch'; Henrik Bengtsson
> Cc: R-bugs@biostat.ku.dk; r-devel@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@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
> > >>
> > >>
> > >>    
> > >>
> > >
> > >  
> > >
> > 
> > ______________________________________________
> > R-devel@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.
> --------------------------------------------------------------
> ----------------
> 
>


[Rd] Help Documentation
Henrik Bengtsson