[Rd] No RTFM?

[(Ted Harding)]

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