[Rd] No RTFM?

[Sean O'Riordain]

I agree with most of what has been said.  And before I go any further
I really do appreciate the work that goes on here.

I think those who are prone to be overly terse and have a tendency to
post RTFM should take a piece of advice from the posting guide..."type
4*runif(1) at the R prompt, and wait this many hours", and consider
*NOT* posting! :-)

As a new user around here (only 9 years), I find the documentation can
be overly terse in places.  I find it easiest to learn by example
(rather than by definition) - so I jump straight to the examples.  But
in many cases the examples or 'Details' just didn't explain the
resulting output - to avoid anything which could possibly be described
as an ad hominem attack, I have to be obscure here... sorry...
whatever(x) produces a table of output which might be obvious to
some... but I do not have years of formal theory of statistics
education, and the printed results are quite ambiguous to me.  Some
documentation runs through every item in the output explaining what it
is instead of assuming that people understand it - if I know it
already I can skip it.  I appreciate that documentation is hard to
write but it is generally better to have too much than too little -
the PDF docs for 2.11.1 on this machine runs to nearly 2,200 pages
which is daunting to read and clearly it would be much bigger if I got
my wish!  Btw. I also buy books to fill in gaps... a quick count
looking around here and I see a dozen books which use R... no doubt
there are at least another dozen in the office.

Sometimes I search endlessly for something in the documentation but
cannot find it because I'm using the wrong set of buzzwords - e.g.
some years ago I wanted to calculate the running total going down a
data.frame - but try as I might I couldn't find 'cumsum()'.

I've found bugs in the past - but didn't dare post a "bug report"...
and six months later it was still a crashing bug...

Generally I will spend at least 8 hours of solid work and include a
night to sleep on a something before considering posting to
r-help/r-devel.  I think that this is why some people have migrated to
other fora e.g. http://stackoverflow.com/questions/tagged/r where one
is less likely to be roasted and insulted.

As I recall there has been more than one call for a beginners help
forum where things are more gentle, but these were "not encouraged".

In the posting guide and in some r-help posts there have been demands
for details of affiliation - my work current work contract (and many
previous contracts) makes it difficult for me to put my work details
on an email to r-help (or similar).

Kind regards,
Sean O'Riordain
un-affiliated...
Dublin, Ireland

On 22 August 2010 03:13, Ted Harding <Ted.Harding at manchester.ac.uk> wrote:
> I've stayed in by back seat in the spectators so far, but I feel
> a comment may be helpful here.
>
> I'm in close sympathy with Hadley Wickham's comment on a "previous
> suggestion by a regular contributor" [Spencer Graves] (below) and
> with the comment by Spencer himself.
>
> We are a community with a variety of attitudes, from prescriptive
> (to the point of disciplinarian) to relaxed and permissive.
> The problem with this sort of discussion is that the former feel
> able to propose detailed prescriptions, while the latter do not
> have a definite "party line" to set out in any sort of detail.
>
> The more specific and detailed the prescriptive proposals become,
> the more they take on forms which could readily be adopted into
> the guidelines for the list, and may therefore seem attractive to
> those who maintain the guidelines. Meanwhile, the permissives have
> not proposed any such specific alternatives.
>
> I do not feel at all comfortable with Paul's suggestions below
> (for reasons which I have explained in-line). To follow these
> suggestions would make posting to R become more and more like
> filling in a Tax Return! (In the days when I had to so this,
> I would work with two photocopies of a 12-page form, a pencil,
> and an eraser, doing 1st draft on copy one, then re-starting
> from scratch 2nd draft on copy 2, all the time consulting a
> 44-page Tax Return Guide and a 16-page Tax Calculation Guide.
> Then comparing the two for agreement, and starting again if
> they didn't. Only when it was all apparently OK would I transcribe
> in ink onto the real Return Form. It would take at least a day.).
>
> Regarding peremptory responses to "RTFM" and the like, if I come
> across one (as when interested in a thread so opening the emails
> about it) I simply delete it with mild irritation (and regret the
> waste of space on the list). And with likely sympathy for the
> person who provoked it (see below).
>
> Regarding the sort of query which can provoke such responses,
> I think one can try to be discriminating. Occasionally they are
> pretty clearly from people who are trying to get someone else
> to do their work without making any effort of their own.
> Appropriate response should fit the case, and need not take the
> form of an automatic "speeding ticket".
>
> Usually, however, they are from naive users who are only beginning
> to find their way in R (and its documentation). Both of these are
> daunting and bewildering tasks for beginners. And not only beginners.
> I've been using R myself for well over 10 years, and seriously for
> nearly 10. I can still wander for a long time through "a maze of
> twisty tunnels, all alike" when trying to track down some essential
> thing (graphics parameters and other options(), in particular, can
> turn into a real "Dungeons and Dragons"). One can even begin to
> wonder whether what one is looking for is documented at all (and
> sometimes it isn't). What with the various introductory manuals
> (which are indeed good), trying '?whatever' and being led off into
> a trail of "See also:"s, trying '??whatever' to try to flush up
> some functions that might be relevant, and the mass of web-pages
> one might be led to on an R Site Search, we have a whole meadow
> full of haystacks in which to search for a needle! And don't try
> to tell me that all the '?...' help pages are models of simplicity,
> clarity, and self-containment!
>
> So, if one recognises such a query, one can try to get some insight
> into what the real obstacle is. If you get that, then a well-chosen
> example along with some clear explanation can help that beginner
> over that problem, encourage them, and give them confidence in their
> own hopes for understanding and using R, and solving such problems
> for themselves in future. Even if it seems that they don't even know
> how to climb over a stile on a footpath, a little encouragement to
> put one foot on the near end of the cross-step, swing the other leg
> over the top and put the other foot on the other end, then swing the
> first foot over and onto the cross-step, then finally hop neatly down
> onto the ground, can evoke an "Ahh!!" and leave them fully equipped
> to deal with the next stile (and some insight into stiles in general).
>
> With R, the analogy would be more like showing (and explaining) the
> manoeuvres which will take them up the first pitch of a rock-climb.
>
> I think that, if one does not feel inclined to take such an approach,
> then it is better simply to move on, maybe deleting the query. There
> is no point in a response which is both discouraging and unhelpful.
> "RTFM" (and variants) is likely to be perceived as a put-down, and
> (unless accompanied by sympathetic detailed guidance) will not help
> to solve the problem. (Some seem to have the mind of a Tax Man, to
> whom all is transparently contained in 44+16 pages of complicated
> and intricately cross-referenced Guides).
>
> So, in my view, the Posting Guide should be a true guide, but should
> avoid giving any impression that jumping through documentation hoops
> is a prerequisite for a valid posting to the list. Therefore it
> should be gentle and general. And it should never be used as an
> Act of Law which defines crimes against the list. There are very
> few of these, compared with the genuine and puzzled questions from
> people who need some help.
>
> See below now for some comments on Paul's suggestions about revisions
> to the Posting Guide.
>
> Best wishes to all,
> Ted.
>
> On 21-Aug-10 22:47:11, Paul Johnson wrote:
>> On Sat, Aug 21, 2010 at 11:04 AM, Hadley Wickham <hadley at rice.edu>
>> wrote:
>>>> previous suggestion by a regular contributor. _I still think a better
>>>> response is not to escalate: _Either ignore the post or say something
>>>> like,
>>>> "I don't understand your question. _Please provide a self-contained
>>>> minimal
>>>> example as suggested in the Posting Guide ... ."
>>>
>>> I agree wholeheartedly. I have tried to do this with the ggplot2
>>> mailing list, and I think it has been extremely successful in
>>> fostering a community that is friendly and polite, yet still provides
>>> excellent technical support (and these days, most of it doesn't come
>>> from me!).
>>>
>>
>> I've been insulted in r-help and its no fun. After Gabor pointed out
>> the logic in it, I have to admit he is right. It does keep traffic
>> down. I don't go there anymore unless I'm completely desperate.
>
> I agree with Hadley, but not with Paul's "logic" bit and the reason.
> There is an implicit assumption about the function of R-help -- it
> appears to be that, if one is a puzzled beginner, one should not post
> to the list (so keep the traffic down ... ) unless one has exhausted
> all the on-line resources (and oneself, and one's time) in an all-out
> effort to find the answer for oneself.
>
> I see the purpose of R-help as providing help with R, at any level.
> The traffic can be at whatever level fills this need. Every "RTFM"
> response adds to the traffic (and so, on that logic, should also
> be discouraged -- especially since it's not useful)! I don't see
> why Paul should have to feel "completely desperate" before daring
> to post to the list.
>
>> I agree also, sometimes RTFM is the right answer, especially if
>> it is stated as "That is discussed on p. 162 of the R Guide for
>> Whatever..."
>> I don't think people are insulted if  you tell them to check
>> something specific.
>
> I agree (see above) that this format of "RTFM" can be a good and
> helpful response, and is unlikely to be seen as a put-down.
>
>> Usually, first time visitors don't know about the R posting guide
>> and when they ask an incomplete question, we should just refer
>> them to it.
>> We don't need the angry tone that we often see, but I don't think
>> people mind being referred. This presupposes the posting guide is
>> helpful.
>
> I agree so far!
>
>> If somebody forgets the posting guide twice, then I think we
>> should all berate and insult them. I mean vigorously :)
>
> But not here! I think insults and put-downs are out of place.
> Possibly one can reply privately, with guidance but not with insults,
> if one feels that it would be "dross" on the list.
>
>> My personal opinion is that the R posting guide could be revised
>> to be more direct. Exhausted, frustrated people don't benefit as
>> much as they could because the document is too long.
>
> I agree.
>
>> This is hard to fix because everything in there was added for a good
>> reasons.  (I've been here long enough to remember a time before the
>> guide, sad to say.)  I tried to reshape the posting guide and I can
>> see that it is a really hard problem.
>>
>> What do you think of this: The priority is to put the most important
>> thing at the top. The second priority is brevity.
>>
>> =============================
>>
>> Posting Guide: How to ask good questions that prompt useful answers
>>
>> People are busy, so ask your question in a useful way.
>>
>> 1. Every question to r-help should begin with the following.
>>
>> A. Output from the command sessionInfo()
>>
>> B. Output from Sys.getlocale()
>>
>> C. Information about how you installed R. Did you make any changes,
>> such as incorporating a BLAS library. If you don't know, ask your
>> system administrator.
>
> Surely not *every* question! Whether these are useful or relevant
> depends on the question. If not, they are (from the point of view
> of anyone trying to get to the point of the question) pure noise.
> In fact, I think most questions that occur don't need these items
> of information (though failure to include them often gets a speeding
> ticket).
>
>> D. If you see an error or something unexpected, your message MUST
>> include the EXACT code that you were running. We mean, ALL of your
>> commands that were run before the error occurred.
>
> If your R program happens to consist of 1000 lines of code, the
> above amounts to an order to include it all -- in all postings
> to R-help. Such a requirement should definitely not be made in the
> posting guide. (D in fact conflicts with the further proposals
> below under D and under E).
>
>>  If you are unsure
>> of what you did, close your session, clean up your code, and start
>> over to reproduce the  problem in the most direct way. Your post
>> MUST include the EXACT VERBATIM error message.
>
> Verbatim error messages are indeed a good thing, and that guidance
> is useful. I would tone down the imperatives, though. More on the
> lines of "Include any error messages verbatim, as returned by R."
>
>> If you are working on a long program that requires a dataset,
>> post the dataset and the program somewhere on the Internet and
>> refer us to it. It is simply not possible to guess about what
>> might be going wrong in your program unless we can see it.
>
> I see this proposal as something which might be useful, but it
> would depend on the context. [see ** below]
>
>> If you don't want to share your data, construct a small example
>> dataset that produces the same problem. Post it and refer us to it.
>
> This might be better worded as "If you can, construct a small
> example with code and data which reproduces the problem." [see ** below]
>
>> E. If you have isolated the problem to a certain part of your project,
>> write a small, self-contained 'working example' that causes the
>> problem and include it with your post.
>
> [**]
> This overlaps with parts of D above.
>
>> Example. Why does this code:
>>
>> dat <- data.frame(x=c(1,2,3), y=c(3,4,5))
>> plot (x, y, data=dat)
>>
>> cause this:
>>
>> Error in plot(x, y, data = dat) : object 'x' not found
>>
>> We can easily reproduce that and explain the problem to you. We can't
>> help with a question like "my plot failed, something about an object
>> was missing."
>
> I think the mini-example of code, and the example of how not to
> asl, are well put.
>
>> 2. How to avoid making the members of r-help angry at you.
>> A. Do not call a problem a "bug" unless you really mean to say that
>>    someone has made a mistake. If you say "bug", they hear
>>    "embarrassing personal flaw" or "gigantic boil".  We know
>>    you don't mean that, but sometimes they forget.
>
> I don't think that occurs often enough to justify making a special
> point of it in the posting guide. I'd leave that out.
>
>> B. Before you write to r-help, search for answers from previous
>> questions.
>>    1. Try Google? Or her cousin Yahoo?
>
> I don't think people should be advised to use Google (or Yahoo)!
> One may get 20,000 hits. See comment to 2 below.
>
>>    2. Try these inside R:
>>
>>       help.search("whatever")
>>       RSiteSearch("whatever")
>>       apropos("whatever")
>
> Good advice. I would also add:
>
>       R site search web interface
>       http://finzi.psych.upenn.edu/nmz.html
>
>> C. Read R-intro, R help pages, and the R FAQs.
>>
>>       ?whatever
>>
>> 3. Do not send your question to r-help unless your question is
>> about R or the base R packages that are supported by the R Core Team.
>
> There are plenty of non-base packages about which questions can be
> fairly asked on R-help! The above should not be in the posting guide.
> See below at [***]
>
>> A. Don't ask statistics questions, unless they fall into the form
>> "Which R procedure or package should I use to conduct an analysis
>> of ..." or
>> "Does anybody have a working example of procedure XYZ?" or "Can I
>> obtain XYZ result from an obect of class ZYX?"
>
> In many cases, people's problems are a combination of shaky grasp
> of R and shaky or incomplete grasp of some part of Statistics.
> A person may well suspect that their problem involves a problem
> with Statistics as such, and may well ask about the statistical
> aspect as well as the R aspect. A good answer would address both.
> Often, the poster may not be aware of the statistical difficulty;
> a good answer would pick that up and include the statistical
> explanation. For example, the unsuspecting may be unaware of
> the "linear separation" phenomenon in binary regression which can
> result in:
>  Warning messages:
>  1: glm.fit: algorithm did not converge
>  2: glm.fit: fitted probabilities numerically 0 or 1 occurred
> A query about that is really a pure statistical matter, and is
> not strictly about R. Nevertheless, it arose out of using R for
> a reason which the user did not understand (and which they may
> suspect to to be due to R). So an explanation sorts it out,
> and helps them along.
>
> I would agree, however, that a question *purely* about Statistics
> would normally be out of order. E.g. "How can I prove that 1*(X==0)
> is an unbiased estimate of exp(-mu) in a Poisson distribution".
>
>> B. If you have trouble with a package from CRAN or elsewhere,
>> write to the author of that package.
>
> It depends on the trouble. I think R-help is usually a good and
> legitimate place to ask, since it is likely to come to the
> attention of several people who have used the package, and may
> have encountered the problem or understand the reasons for it.
> They may even have better solutions than the author of the package
> could provide! I have myself had the experience of discussing
> a problem with a package on R-help, locating the problem (and
> devising its solution) in the code, leading to my mailing the
> package maintainer who was not aware of the problem!
>
>> r-help might be a good place to ask, "I've been using package
>> XYZ and the author seems to have abandoned the project.
>> Does anybody know of a replacement?" Otherwise, don't.
>
> For reasons above, I don't agree with this,
>
>> Note that the Bioconductor repository is not part of "R" proper
>> and you should address questions about Bioconductor to their
>> support framework.
>
> Presumably you mean the various special lists for Bioconductor?
> In such a case, that is fair enough, since anyhone using Bioconductor
> is likely to be subscribed to such lists anyway. (But they wouldn't
> need to be told about this in the general Posting Guide).
>
> [***]
> There are many packages, however, such as combinat, boot, cluster,
> etc. which are not part of R-base (though many of them are in
> "recommended") which are in frequent use, and questions about them
> to R-help are perfectly in order (and the individual author of
> such a package does not want to be the sole recipient of frequent
> questions about it -- the R-help community can carry the load
> better with its "distributed model").
>
>> C. If you are writing code for R itself, or if you are developing a
>>    package, send your question to r-devel, rather than r-help.
>
> It depends on the question!
>
>> D. For operating-system or R interface questions, there are dedicated
>> lists. See R-sig-Mac, R-sig-Debian, R-sig-Fedora, etc.
>
> Fair enough (in most cases).
>
>> ==============================
>>
>> It will be necessary to add, toward the end, the part about
>> "be polite when posting."
>
> And, since a reply is also a posting, "be polite when responding"!
>
>> And along the lines of the "No RTFM" policy, I think we should say
>> "All RTFM answers should include an exact document and section
>> number." It is certainly insulting to answer a question about plot
>> with the one line
>>
>> ?plot
>>
>> but it is not insulting to say "In ?plot, check the "Details"
>> section and run the example code."
>
> Fair enough -- and indeed this is an example of a helpful and
> sufficient (for most people) response, and therefore is not in
> the "RTFM" category.
>
>
> --------------------------------------------------------------------
> E-Mail: (Ted Harding) <Ted.Harding at manchester.ac.uk>
> Fax-to-email: +44 (0)870 094 0861
> Date: 22-Aug-10                                       Time: 03:13:22
> ------------------------------ XFMail ------------------------------
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>