[R] draft of posting guide

[Gabor Grothendieck]

Thanks for your effort.  Here are some comments.

1. The guidelines seem only to cover people
_asking_ questions.  What about those answering?

2. I think "bug" needs to be taken in the broader
sense of a problem.  Such problems are not limited
to discrepancies between documentation and
implementation.  The real serious problems are
design problems and may not represent such
deviations at all.  If the behavior is unexpected
it may very well be a problem even if its not a
bug in the narrow sense.

3. Rude answers are never warranted.

4. Its too long and there are too many "rules".  

5. The tone should be friendlier -- more helpful
and inviting.  Words like "lazy" should be
eliminated.  Although R is not a commercial
enterprise and its users are not customers in the
usual sense, its users should still be treated
with respect and encouraged rather than
admonished.  A customer oriented attitude will
be appreciated and encourage more participation.
The purpose of this should not be so
much to tell posters what they can do and not do
but to help them elicit useful responses and
to help responders provide userful answers.

6. Points should be numbered so they can be
referred to.  Each one should have an address so
that one can refer to them individually like this:
http://www.r-project.org/...whatever.../etiquette.html#3.1

7. I personally find the statistics questions
interesting and would not like to see guidelines
about not posting statistical problems.

8. Where documents are referred to, provide a URL.
Where R is being referred to point that out.  For
example, help.search is an R command.  This may be
obvious to some but it might not be obvious to
someone just coming to R.

9. It might be worthwhile to point out that the
following google search works:       
   whatever site:r-project.org

The real problem with the lists is not the
posters.  The real problems are:

- rude answers

- insufficient discussion about the direction and
  design and, in general, higher level issues.  If
  you compare this to ruby, python, perl and lua
  there are all sorts of interesting proposals and
  discussions on this on their lists with little
  counterpart on R's.

> Date: Fri, 19 Dec 2003 22:55:53 -0700 
> From: Tony Plate <tplate at acm.org>
> To: <r-help at stat.math.ethz.ch> 
> Subject: [R] draft of posting guide 
> 
>  
>  
> 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
> 
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-help
>