[Rd] No RTFM?

[Ben Bolker]

Paul Johnson <pauljohn32 <at> gmail.com> writes:

> 

 [snip: lots more snippage to try get gmane to let me post]

> What do you think of this: The priority is to put the most important
> thing at the top. The second priority is brevity.

  I really like this.
  Some suggestions:

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

   I would make this optional or put it further down. I don't see that
many problems on the list that are due to non-standard installations.
Most of the most clueless people are (a) using stock installations
and/or (b) don't even know who installed R on the computer they are
using. I don't mind sending them to find out/ask if it's a real
issue, but it feels like an unnecessary hurdle.

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

   This is where we have to emphasize 'small, reproducible example'
more strongly -- perhaps move the next item up. 
I dread the pages and pages of random R-session crap
that will be posted following this advice literally ...
 
> 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.

  [note that there is already information on 'what is a bug' in the
posting guide -- I think -- or maybe it's the R FAQ]

> 
> B. Before you write to r-help, search for answers from previous questions.
>    1. Try Google? Or her cousin Yahoo?
 
    This should be for more general statistics questions, and perhaps
put second.

>    2. Try these inside R:
> 
>       help.search("whatever")
>       RSiteSearch("whatever")
>       apropos("whatever")

  perhaps add
  install.packages("sos"); library(sos); findFn("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.  

 ^^^ maintainer; use maintainer("whatever") to find their e-mail address.

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

  Is there any point posting this on the Wiki and letting people
hack at it?

  Ben