[Rd] Help Documentation

[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
>>
>>
>>    
>>
>
>  
>