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...
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
>
>
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 > >
On Mon, 29 Mar 2004 09:54:17 -0500, Duncan Murdoch <dmurdoch@pair.com> wrote :>You can normally see a webified version of the log online, but I seem >to have misplaced the URL, and developer.r-project.org is offline.Found it: <http://anoncvs.r-project.org/cgi-bin/cvsweb.cgi/>. Most documentation is in R/src/library/<package>/man, with the manuals in R/doc/manual. Because of the package reorganization about 3 months ago, most of the files in the stats package (and other files that got moved) show limited revision history; you need to go to the "Attic" of the old package to see the older history. Generally the log comment at the time of the move will tell you where to go. Duncan Murdoch