[R] draft of posting guide
Tony Plate
tplate at acm.org
Sat Dec 20 06:55:53 CET 2003
Here is a first draft of a guide for posters to r-help and
r-devel. Suggestions on how to improve any aspect of it are
most welcome. Suggestions on ways to make it more concise
are especially welcome. Comments on which parts you like
or don't like are welcome. Rather than clutter up R-help with
lots of small corrections etc, please send them to me, and I
will try to incorporate and summarize appropriately.
I've left out most HTML formatting (except for headings) to
make it readable -- I'll insert that later (to conform with
the style on the other pages at r-project.org.) I've placed
"???" in places where feedback is specifically needed.
<h2>Posting Guide: How to ask good questions that prompt useful
answers</h2>
* Remember that R is free software, constructed and
maintained by volunteers. They have various reasons for
contributing to R, but often have limited time. Remember
that no one owes you anything, and if you rude or
disrespectful in your questions, you are likely to either
be ignored or have the sentiment returned to you.
* The R mailing lists are primarily intended for questions
and discussion about the R software. However, sometimes
questions about statistical methodology are posted. [???
are these discouraged/tolerated/... ???] People are far
less likely to respond to these types of questions than to
questions about the R software. Depending on how much the
post shows thought and background research, responses may
merely (and sometimes brusquely) suggest that you should
be seeking statistical consulting advice elsewhere.
Sometimes, if the question is well-asked AND of interest
to someone on the list, you may get an informative,
up-to-date answer.
* Don't expect R-help to teach you basic statistics. That's
what statistics textbooks and statistics classes are for.
* If you have a question about R that you want answered,
don't be lazy. Do your homework first. If it is clear
that you have done your homework, your are far more likely
to get an informative response. The type of homework that
needs to be done depends on the type of question --
details are in the following paragraphs.
* Make it easy for people to answer your question: be clear
and concise, remove unnecessary details, and, if they
might be useful, provide brief examples.
* A much more detailed (and highly recommended) essay on how
to ask questions on mailing lists about software is Eric
Raymond's "How To Ask Questions The Smart Way"
http://www.catb.org/~esr/faqs/smart-questions.html. (Note
that catb.org has no association with the R project and
will not respond to questions concerning R.)
<h3>Homework before posting a question</h3>
Before posting any question, try to do at least the
following background research:
* help.search("<keyword>") at least 3 times, each time
with a keyword from your problem description (including
any synonyms you can think of)
* read the online help for relevant functions (usually can
be accessed by typing "?functionname", e.g., "?prod" at
the prompt.)
* search the R-faq (and the R-windows-faq if it might be
relevant)
* search R-help archives (see under the heading "Archives
and Search Facilities" above)
<h3>Questions about specific functions</h3>
* If you have a question about a particular function, make
sure you have thoroughly read the documentation for that
function (often accessible via help("<functionname>"),
e.g., help("summary")). If you don't understand some
aspect of the documentation, it's OK to post a question
about that, but do demonstrate that you have at least
tried to read it (e.g., by including in your post the
specific passage from the documentation, and stating why
you don't understand it.) In some cases, the
documentation for a function may be in a book, e.g., as
with the MASS package. If this is the case, make sure you
consult the appropriate book before posting. This may
require a visit to the bookstore or library, and if you
are posting from a rich country or commercial organization
it will be assumed you have access to such resources.
<h3>Questions about specific problems</h3>
* If you have a question about what functions can be used to
approach a particular problem, but you are unable to find
anything with a basic search, then in your posting you
should state this, and the keywords you used, as well as
giving a clear description of your problem. It's best to
keep this problem description as high level as possible.
For example if you want to cluster some data so that you
can make a postscript plot of hierarchical clusters, then
by stating this you are more likely to get useful answers
than by asking some lower-level question like "how to I
specify a .ps suffix to a filename argument for the
diana() function?" (this question intentionally nonsense).
* If you have a question about how to manipulate data, or a
question about how to use a function on some specific
data, you are far more likely to get a fast and useful
response if you supply a concise and reproducible example.
This might consist of just some example data, followed by
a precise description of the data object that you want to
transform it to. Optionally, you could include failed
attempts you made to solve the problem, with the question
being how to modify these so they work. In all cases,
these should be R code (with output) that other R-help
subscribers can cut and paste into their R command window.
DO NOT post large examples -- if you problem is with a
large data set, then edit it down to the bare essentials
before posting. However, do say what the size of the
original data is -- that might have some bearing on the
best solution. For example, if you need to turn a 200 by
50 numeric matrix into rows of records with three fields,
don't post your 10000 element matrix, but condense it to
something like the following:
If I have a matrix x as follows:
> x <- matrix(1:8, nrow=4, ncol=2, dimnames=list(c("A","B","C","D"), c("x","y"))
> x
x y
A 1 5
B 2 6
C 3 7
D 4 8
>
how can I turn it into a dataframe with three columns,
named "row", "col", and "value", which have the dimension
names as the values of "row" and "col", like this:
> x.df
row col value
1 A x 1
...
(To which the answer might be:
> x.df <- reshape(data.frame(row=rownames(x), x), direction="long", varying=list(colnames(x)),
+ times=colnames(x), v.names="value", timevar="col", idvar="row")
??? are there better answers than this using reshape() ???
)
Note that if you if have matrix or data frame data, it is
sufficient to just include the printed version of it in
your question, and other posters can copy this onto their
clipboard and read it into R with a command like: > x <-
read.table("clipboard", header=T) or > x <-
as.matrix(read.table("clipboard", header=T)) [??? does
something like this work under Unix ???]
<h3>Questions about surprising behavior or possible bugs</h3>
* If you suspect there is a bug in a particular function in
R, be very careful about saying "this is a bug".
Well-educated people of good intent can differ about many
things, including what is the most desirable (or even
"correct") behavior for mathematical and statistical
software. Note that some particular behavior is generally
considered to be a bug ONLY if the behavior of the
software contradicts the documentation. So before you
claim a bug, make sure you read the documentation very
carefully. If you're not completely and utterly sure
something is a bug, post a question to r-help, not a bug
report to r-devel. If some behavior seems very strange to
you, e.g., you think prod(numeric(0)) should be NA, not 1,
then read the documentation. If that does not make things
clear to you, don't post on r-devel saying "I found a bug:
prod(numeric(0)) should be NA, not 1." Instead, post on
r-help, asking"Is it the intended behavior that
prod(numeric(0)) is 1? If so, can anyone tell me why?"
Note that incorrect bug reports put into the R-project
bug-tracking system are a big waste of people's time
because one of the R-core members must manually respond to
the bug report to clear it out. Before you post a bug
report, make sure you read the section on how to post a
bug report in the R-faq
"http://CRAN.R-project.org/doc/FAQ/R-FAQ.html#R Bugs".
Also, see Simon Tatham's essay at
http://www.chiark.greenend.org.uk/~sgtatham/bugs.html
* In any question regarding unusual or unexpected behavior,
or interaction with the operating system, always state the
version of R you are using (which is like "1.8.1", NOT
just "1.8"), the operating system you are using, and
whether you installed a pre-compiled binary version of R
or compiled it yourself.
<h3>Common posting mistakes</h3>
Doing any of the following may result in you getting a
response that you may find rude or insulting. (However,
such a response may be justified in the eyes of some because
you have wasted people's time or unjustly insulted people's
work.)
* Not doing your homework before posting a question.
* Asking R-help to do your classroom homework for you
(remember that many of the subscribers of R-help are
university professors and can recognize homework questions
with great speed and accuracy)
* Claiming that something is a bug when in fact the software
is working as intended and documented, just not in the way
you first expected.
* Claiming that some commonly used function is not behaving
in what you think is a sensible manner (it's far more
productive and polite to just ask why it behaves the way
it does if you think it is odd -- but only after reading
all the relevant documentation!)
<h3>Final words</h3>
It is an skill to ask good questions. If at first you don't
get the answers that are useful to you, don't get
discouraged. If you feel insulted by some response to a
post of yours, don't make any hasty response in return
(you're as likely as not to regret it.) Go read Eric
Raymond's essay -
http://www.catb.org/~esr/faqs/smart-questions.html - it has
some explanation of people's behavior on technical mailing
lists.
Think carefully before you respond to another poster with a
demeaning or insulting comment. Is it really necessary?
What will it achieve? Remember that it's far easier to
maintain the respect of other people if you are polite -- if
you are rude your technical contributions had better be 110%
correct, otherwise you'll just look like an ignorant jerk.
END OF POSTING GUIDE
Since Martin Maechler indicated such a guide would be
welcome, I'm assuming it could go somewhere on the
R-project.org site. It could be placed wherever the
R-project site maintainers wish, though to be most useful it
should be easy to find by clicking on the link at the bottom
of each posting to r-help and r-devel (ie
https://www.stat.math.ethz.ch/mailman/listinfo/r-help &
https://www.stat.math.ethz.ch/mailman/listinfo/r-devel).
One possibility would be to make it a section of the
"General Instructions" page (
http://www.r-project.org/mail). Another would be to make an
independent "Posting Guide" page.
In either case, some more specific words on
https://www.stat.math.ethz.ch/mailman/listinfo/r-help than
just "Please read the General Instructions on the R Mailing
Lists page." might be helpful, e.g.: "For some guidelines
on what to post and how to post in a way that maximizes your
chances of getting useful answers, please read the posting
guide..."
-- Tony Plate
More information about the R-help
mailing list