[Rd] No RTFM?

[Paul Johnson]

Hey Ben:

One of my colleagues bought your book and was reading it during a
faculty meeting last Tuesday.  Everybody kept asking what's that?

If you know how to put it in the wiki, would you please do it and let
us know where it is.  I was involved with an R wiki about 5 or 6 years
ago, but completely lost track of it.

I'm going to keep pushing for sharp, clear guidelines.  If I could get
R-help set up as a template for messages like  bugzilla, I think it
would be awesome! To disagree with Ted. People won't mind giving us
what we need, as long as we tell them exactly what to do. We save
ourselves the circle of "give us sessionInfo()" and "give us your
LANG" and 'what version is that' and so forth.

But I'll consider it a victory if we can get the requirement of
sessionInfo() in as the first thing in the posting guide !

I agree that "which packages can we help with" in r-help is a good
question. I had in mind that we should field questions about anything
in the R tarball, including the recommended ones. I think I did not
use the right words when I tried to express that.  Maybe we just need
to list the packages to be clear.  Things like "foreign" that have
passed from the ownership of the original writer to the R Core Team
are certainly eligible.

I also admit that I have not looked at R-FAQ since about 2005, and I
don't want to duplicate that effort.  If R-FAQ has a nice concise list
of ways to get information about specific things, the posting guide
might just refer to that section by name/number, rather than
duplicate.  I'm torn here, because people often assume that if you
give them a link, it must not be important (thats why you left it
out).

pj

On Sat, Aug 21, 2010 at 6:04 PM, Ben Bolker <bbolker at gmail.com> wrote:
> 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
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>



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