[Rd] No RTFM?

[Paul Johnson]

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

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. If somebody forgets the posting guide twice, then I think we
should all berate and insult them. I mean vigorously :)

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.

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.

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

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.

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.

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.

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."

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.

B. Before you write to r-help, search for answers from previous questions.
   1. Try Google? Or her cousin Yahoo?
   2. Try these inside R:

      help.search("whatever")
      RSiteSearch("whatever")
      apropos("whatever")

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.

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?"

B. If you have trouble with a package from CRAN or elsewhere, write to
the author of that package.  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.

Note that the Bioconductor repository is not part of "R" proper and
you should address questions about Bioconductor to their support framework.

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.

D. For operating-system or R interface questions, there are dedicated
lists. See R-sig-Mac, R-sig-Debian, R-sig-Fedora, etc.

==============================

It will be necessary to add, toward the end, the part about "be polite
when posting."

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."

pj
-- 
Paul E. Johnson
Professor, Political Science
1541 Lilac Lane, Room 504
University of Kansas