People read the posting guide yet they are still unable to create an acceptable post. e.g. https://stat.ethz.ch/pipermail/r-help/2008-June/164092.html I think the problem is that the guide is not clear or concise enough. I suggest we add a summary at the beginning which gets to the heart of what a poster is expected to provide: Summary To maximize your change of getting a response when posting provide (1) commented, (2) minimal, (3) self-contained and (4) reproducible code. (This one line summary also appears at the end of each message to r-help.) "Self-contained" and "reproducible" mean that a responder can copy the questioner's code to the clipboard, paste it into their R session and see the same problem you as the questioner see. Note that dput(mydata) will display mydata in a reproducible way. Self-contained and reproducible are needed because: (1) Self-Effort. It shows that the questioner tried to solve the problem by themself first. (2) Test framework. Often the responder needs to play with the code a bit in order to respond or at least to give the best answer. They can't do that without a test framework that includes the data and the code to run it and its not fair to ask them to not only answer the question but also to come up with test data and to complete incomplete code. (3) Archives. Questions and answers go into the archives so they are not only for the benefit of of the questioner but also for the benefit of all future searchers of the archive. That means that its not finished if you have solved the problem for yourself. You still need to ensure that the thread has a complete solution. (For that reason its also important to give a meaningful subject to each post.) "Commented" and "minimal" also reduce the time it takes to understand the problem. Don't just dump your code as is into the message since you are just wasting your own time. Its not likely anyone will answer a message if the questioner has not taken the time to reduce it to its essential elements. Surprisingly, quite often understanding what the problem is takes the responder most of the time -- not solving the problem. Once the question is actually understood its often quite fast to answer. Thus in addition to posting it in a minimal form, comment on it sufficiently so that the responder knows what the code does and is intended to produce. It may be obvious to the questioner who is embroiled in the problem but that does not mean its obvious to others. Introduction .... rest of posting guide ...
I'd recommend either having two or three good examples of acceptable posts at the end of the posting guide or at least some hyperlinks to good examples. Two or three contrasting poor posts would also be helpful. If people can see a brief email with working code AND the ever-essential sessionInfo() output I think they will be more likely to compose a reasonable post. It's not rocket science when you see a few examples of good posts, but reading lines and lines of text describing a good post clearly is not getting through to many people. Steve McKinney -----Original Message----- From: r-devel-bounces at r-project.org on behalf of Gabor Grothendieck Sent: Fri 6/6/2008 10:30 AM To: R Development List Subject: [Rd] Posting Guide People read the posting guide yet they are still unable to create an acceptable post. e.g. https://stat.ethz.ch/pipermail/r-help/2008-June/164092.html I think the problem is that the guide is not clear or concise enough. I suggest we add a summary at the beginning which gets to the heart of what a poster is expected to provide: Summary To maximize your change of getting a response when posting provide (1) commented, (2) minimal, (3) self-contained and (4) reproducible code. (This one line summary also appears at the end of each message to r-help.) "Self-contained" and "reproducible" mean that a responder can copy the questioner's code to the clipboard, paste it into their R session and see the same problem you as the questioner see. Note that dput(mydata) will display mydata in a reproducible way. Self-contained and reproducible are needed because: (1) Self-Effort. It shows that the questioner tried to solve the problem by themself first. (2) Test framework. Often the responder needs to play with the code a bit in order to respond or at least to give the best answer. They can't do that without a test framework that includes the data and the code to run it and its not fair to ask them to not only answer the question but also to come up with test data and to complete incomplete code. (3) Archives. Questions and answers go into the archives so they are not only for the benefit of of the questioner but also for the benefit of all future searchers of the archive. That means that its not finished if you have solved the problem for yourself. You still need to ensure that the thread has a complete solution. (For that reason its also important to give a meaningful subject to each post.) "Commented" and "minimal" also reduce the time it takes to understand the problem. Don't just dump your code as is into the message since you are just wasting your own time. Its not likely anyone will answer a message if the questioner has not taken the time to reduce it to its essential elements. Surprisingly, quite often understanding what the problem is takes the responder most of the time -- not solving the problem. Once the question is actually understood its often quite fast to answer. Thus in addition to posting it in a minimal form, comment on it sufficiently so that the responder knows what the code does and is intended to produce. It may be obvious to the questioner who is embroiled in the problem but that does not mean its obvious to others. Introduction .... rest of posting guide ... ______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Gabor, I agree. Furthermore I think it might be useful to add that in my experience (and I'm sure others as well) that the process of creating a simple reproduceable example for an email to r-help will in most cases clarify what I'm trying to do and actually solve my own problem for me - once or twice I've been tempted to email my problem and my own solution for the archive. As a side note I tend to put a fair bit of work (i.e. measured in days of calendar time and hours of work) for fear of being abused on the list for not doing enough prep work. Fear is probably not the idea motivator though... Regards, Sean 2008/6/6 Gabor Grothendieck <ggrothendieck at gmail.com>:> People read the posting guide yet they are still unable to create an acceptable > post. e.g. > https://stat.ethz.ch/pipermail/r-help/2008-June/164092.html > > I think the problem is that the guide is not clear or concise enough. > I suggest we add a summary at the beginning which gets to the heart > of what a poster is expected to provide: > > Summary > > To maximize your change of getting a response when posting provide (1) > commented, > (2) minimal, (3) self-contained and (4) reproducible code. (This one > line summary > also appears at the end of each message to r-help.) > > "Self-contained" and "reproducible" mean that a responder can copy the > questioner's code to > the clipboard, paste it into their R session and see the same problem > you as the questioner > see. Note that dput(mydata) will display mydata in a reproducible way. > Self-contained and reproducible are needed because: > (1) Self-Effort. It shows that the questioner tried to solve the > problem by themself first. > (2) Test framework. Often the responder needs to play with the code a > bit in order to respond > or at least to give the best answer. They can't do that without a > test framework that includes > the data and the code to run it and its not fair to ask them to not > only answer the question but > also to come up with test data and to complete incomplete code. > (3) Archives. Questions and answers go into the archives so they are > not only for the benefit of > of the questioner but also for the benefit of all future searchers of > the archive. That means > that its not finished if you have solved the problem for yourself. > You still need to ensure that > the thread has a complete solution. (For that reason its also > important to give a meaningful > subject to each post.) > > "Commented" and "minimal" also reduce the time it takes to understand > the problem. > Don't just dump your code as is into the message since you are just > wasting your own > time. Its not likely anyone will answer a message if the questioner > has not taken the > time to reduce it to its essential elements. Surprisingly, quite > often understanding what > the problem is takes the responder most of the time -- not solving the > problem. Once the > question is actually understood its often quite fast to answer. Thus > in addition to posting > it in a minimal form, comment on it sufficiently so that the responder > knows what the code > does and is intended to produce. It may be obvious to the questioner > who is embroiled in > the problem but that does not mean its obvious to others. > > Introduction > > .... rest of posting guide ... > > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel >
Here is a second version of the summary. Its been rearranged to
place most important info at top. Also shortened it a bit.
It still needs links to example posts, as suggested. Anyone?
Summary
Surprisingly, the main problem for responders is not to answer the
posted questions but to quickly figure out what the question is, reproduce
it in their own R session and test their answer.
Test Framework. To faciliate that provide a test framework of:
(1) reproducible self-contained minimal code and data. That means
responders can copy it from the questioner's post and paste it
into their session to see the same output without having to
enter even one R command.
NB. dput(mydata) produces mydata in reproducible form.
(2) comments/explanations of what the code is intended to produce and
(3) versions of all software used, e.g. sessionInfo().
Without self-contained reproducible code the responder must not only
understand the question but must also create a test framework and that
typically takes more time than answering the question! Its not fair
to ask the responder to provide all that on top of answering the
question. Do NOT assume the problem is so simple that it is not
necessary.
Effort. The effort taken to reduce the problem to its essentials and
produce a test framework often solves the problem avoiding the need
for a post in the first place. It at the least shows that the
questioner tried to solve it themself.
Subscribers. The questioner should ensure that the thread is complete
and that it has an appropriate Subject. The purpose of the post is
not only to help the questioner but also the other list subscribers
and those later searching the archives.
On Fri, Jun 6, 2008 at 1:30 PM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:> People read the posting guide yet they are still unable to create an
acceptable
> post. e.g.
> https://stat.ethz.ch/pipermail/r-help/2008-June/164092.html
>
> I think the problem is that the guide is not clear or concise enough.
> I suggest we add a summary at the beginning which gets to the heart
> of what a poster is expected to provide:
>
> Summary
>
> To maximize your change of getting a response when posting provide (1)
> commented,
> (2) minimal, (3) self-contained and (4) reproducible code. (This one
> line summary
> also appears at the end of each message to r-help.)
>
> "Self-contained" and "reproducible" mean that a
responder can copy the
> questioner's code to
> the clipboard, paste it into their R session and see the same problem
> you as the questioner
> see. Note that dput(mydata) will display mydata in a reproducible way.
> Self-contained and reproducible are needed because:
> (1) Self-Effort. It shows that the questioner tried to solve the
> problem by themself first.
> (2) Test framework. Often the responder needs to play with the code a
> bit in order to respond
> or at least to give the best answer. They can't do that without a
> test framework that includes
> the data and the code to run it and its not fair to ask them to not
> only answer the question but
> also to come up with test data and to complete incomplete code.
> (3) Archives. Questions and answers go into the archives so they are
> not only for the benefit of
> of the questioner but also for the benefit of all future searchers of
> the archive. That means
> that its not finished if you have solved the problem for yourself.
> You still need to ensure that
> the thread has a complete solution. (For that reason its also
> important to give a meaningful
> subject to each post.)
>
> "Commented" and "minimal" also reduce the time it takes
to understand
> the problem.
> Don't just dump your code as is into the message since you are just
> wasting your own
> time. Its not likely anyone will answer a message if the questioner
> has not taken the
> time to reduce it to its essential elements. Surprisingly, quite
> often understanding what
> the problem is takes the responder most of the time -- not solving the
> problem. Once the
> question is actually understood its often quite fast to answer. Thus
> in addition to posting
> it in a minimal form, comment on it sufficiently so that the responder
> knows what the code
> does and is intended to produce. It may be obvious to the questioner
> who is embroiled in
> the problem but that does not mean its obvious to others.
>
> Introduction
>
> .... rest of posting guide ...
>