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 ...
Posting Guide
13 messages · Steven McKinney, Sean O'Riordain, Gabor Grothendieck +4 more
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 ...
Here's my attempt at making a little more friendly:
Removed self-contained - implied by reproducible
Used slightly less formal language (and you instead of the questioner)
Fixed a couple of spelling mistakes
Removed references to testing framework - I don't think that that term
needs to be introduced
-------
For most questions, the main problem isn't answering the question, but
understanding exactly what the question is, reproducing the problem and
checking the answer. To make easy for others to help you, you should provide:
(1) reproducible, minimal code, and the data needed to run it. That means
others can copy and paste from your email and see the same
output that you did. An easy way to include data in an email is to
include the output of dput(mydata)
(2) comments/explanations of what the code is supposed to do, and
(3) the version of R and the packages that you used, easily produced by
sessionInfo().
Without reproducible code, others have to spend a lot of time
recreating the problem so that they can provide an answer that works.
Do NOT assume the problem is so simple that it is not necessary.
This can seem like a lot of work, but it often pays off by revealing the
solution without having to ask anyone else. Even if it doesn't, your effort
shows the list that you have tried to solve it yourself.
It's also worthwhile spending some time writing a good subject line that
succinctly summarises your problem. This also helps others trying to solve the
same problem in the future as they can more easily locate relevant messages.
Hadley
On Sat, Jun 7, 2008 at 8:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Might I suggest the following two additions: For item (1), I suggest adding to the end of it something like "Consider attaching this output/data as a txt file if it is too large, or consider using one of the built in data sets (as produced e.g. by data() ) if they suffice to illustrate the problem." I find it rather distracting to have to wade through pages and pages of the the output of dput before I can read the questions to be answered, and perhaps they are the kinds of questions that indeed can be answered without that output, in which case having it pasted straight into the text can be quite distracting. Unless we can at least convince them to append the output to the end, instead of the core of the message. With regards to sessionInfo, I would consider it equally important, many times, to have the output of ls(), to make sure that functions etc are not masked by user defined global variables. But perhaps I'm alone in that? At least mention clearly that the code provided should be reproducible on a clean R workspace, or something like that? I think creating this summary section to the posting guide is a great idea. The posting guide, though chock full with useful information on how to do a proper post, ends up having just way too much information, resulting, as experienced, in people not following it. Haris Skiadas Department of Mathematics and Computer Science Hanover College
On Jun 7, 2008, at 10:48 AM, hadley wickham wrote:
Here's my attempt at making a little more friendly:
Removed self-contained - implied by reproducible
Used slightly less formal language (and you instead of the questioner)
Fixed a couple of spelling mistakes
Removed references to testing framework - I don't think that that term
needs to be introduced
-------
For most questions, the main problem isn't answering the question, but
understanding exactly what the question is, reproducing the problem
and
checking the answer. To make easy for others to help you, you
should provide:
(1) reproducible, minimal code, and the data needed to run it.
That means
others can copy and paste from your email and see the same
output that you did. An easy way to include data in an email
is to
include the output of dput(mydata)
(2) comments/explanations of what the code is supposed to do, and
(3) the version of R and the packages that you used, easily
produced by
sessionInfo().
Without reproducible code, others have to spend a lot of time
recreating the problem so that they can provide an answer that works.
Do NOT assume the problem is so simple that it is not necessary.
This can seem like a lot of work, but it often pays off by
revealing the
solution without having to ask anyone else. Even if it doesn't,
your effort
shows the list that you have tried to solve it yourself.
It's also worthwhile spending some time writing a good subject line
that
succinctly summarises your problem. This also helps others trying
to solve the
same problem in the future as they can more easily locate relevant
messages.
Hadley
On Sat, Jun 7, 2008 at 8:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
Here is another update. I have added the following:
- info about using a fresh R session. (In that case ls() output is less
essential; however, the developers of sessionInfo() might consider
adding that as a default or as an option.)
- questioner should consider use of functions.
- for data use dump(x, file = "") to reproducibly display data or use
builtin datasets listed by data()
- minimal versions of slow code should be presented in cases where
questioner is looking for faster code.
- we still need to add links to illustrative sample questions in r-help
The following were not added for the reason cited:
- guide is not just for questioners. Important to distinguish roles
of questioner, responder and reader.
- what is to be provided ought to be given a name to make it easier
to refer to. An unlabelled set of points is too vague. Test
framework seems appropriately descriptive. By giving it a name
one can request that a questioner "provide a test framework as
defined in the posting guide summary".
- self contained is not implied by reproducible. Reproducible
only means that info is available somewhere -- not that its all
available right in the questioner's post and all in a manner that
is readily accessible.
- focus should be on making data minimal. Don't like attachments
since responder must save them and read them in. It encourages
use of large rather than minimal data sets.
Summary
Surprisingly, the main problem for responders is not to answer the
question but to quickly figure out what the question is, reproduce it
in their own R session and test their answer.
Test Framework. To faciliate this provide a test framework of:
(1) minimal reproducible self-contained commented code and data
that has been run in a fresh R session. That means code and
data have been cut down as far as possible to the essentials
needed to illustrate the problem and were run are just after
starting up R. Also it means that its possible for responders
to just copy the code and data section from the questioner's
post to the clipboard and paste it into their session to see
the same output without having to enter even one R command.
In some cases there may be an advantage to present the code as
a function and in the case of needing a speedup be sure to post
a minimal version of the slow code. Use builtin data sets such
as those listed by data() to illustrate problem or reduce your
data to a minimum and present it reproducibly by using:
dump("mydata", file = "")
(2) comments/explanation of what the code is intended to produce
-- Don't assume its obvious!
(3) versions of all software used, e.g. sessionInfo(),
or R.version.string; packageDescription("zoo")$Version
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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
1 day later
Whilst it is a good idea to improve the posting guide, it seems to me
that it would be useful to have a function along the lines of
bug.report(), to help a potential questioner make sure they have done
their homework and have the relevant information to put into a post to
R-help.
Even those of us who know what ought to go into a post can sometimes
forget to check something obvious - I recently got caught out by not
checking an error was reproducible in the patched version for example.
So I have written a help.request() function (see below), which
- prompts the user to check the relevant resources, stopping and opening
the relevant url where necessary
- checks their R version is up-to-date (in a rather messy way - please
suggest improvements!)
- prompts them to prepare appropriate example code and test it in a
fresh R session
- prompts them to give a meaningful subject line
- automatically adds system info to the post (as in bug.report)
- sends the message for them (ensuring a fresh thread is started)
Is this an idea worth taking further? I would be happy to make
improvements as suggested and write a help file if so.
Heather
------------------------------------------------------------
help.request <- function (subject = "",
ccaddress = Sys.getenv("USER"),
method = getOption("mailer"),
address = "r-help at R-project.org",
file = "R.help.request")
{
no <- function(answer) answer == "n"
yes <- function(answer) answer == "y"
go <- function(url) {
cat("Please do this first - the site has been loaded in your
web browser\n")
browseURL(url)
}
cat("Checklist:\n")
post <- readline("Have you read the posting guide? (y/n) ")
if (no(post)) return(go("http://www.r-project.org/posting-guide.html"))
FAQ <- readline("Have you checked the FAQ? (y/n) ")
if (no(FAQ)) return(go("http://cran.r-project.org/faqs.html"))
intro <- readline("Have you checked An Introduction to R? (y/n) ")
if (no(intro))
return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
NEWS <- readline("Have you checked the NEWS of the latest
development release? (y/n) ")
if (no(NEWS)) return(go("https://svn.r-project.org/R/trunk/NEWS"))
rsitesearch <- readline("Have you looked on RSiteSearch? (y/n) ")
if (no(rsitesearch)) {
cat("Please do this first - the site has been loaded in your
web browser\n")
return(RSiteSearch(subject))
}
inf <- sessionInfo()
if ("otherPkgs" %in% names(inf)){
other <- readline("You have packages other than the base
packages loaded.",
"\nIf your query relates to one of these,
have you ",
"checked any corresponding books/manuals \nand ",
"considered contacting the package
maintainer? (y/n/NA) ")
if(no(other)) return("Please do this first.")
}
man <- url("http://cran.r-project.org/manuals.html")
ver <- scan(man, what = character(0), sep = "\n", skip = 13, nlines
= 1, quiet = TRUE)
major <- as.numeric(substr(ver, start = 18, stop = 18))
minor <- as.numeric(substr(ver, start = 20, stop = 22))
if (major < as.numeric(R.Version()$major) ||
minor < as.numeric(R.Version()$major)) {
update <- readline("Your R version is out-of-date, would you
like to update now? (y/n) ")
if (yes(update)) {
return(go(getOption("repos")))
}
}
## To get long prompt!
cat("Have you written example code that is\n",
"- minimal\n - reproducible\n - self-contained\n - commented",
"\nusing data that is either\n",
"- constructed by the code\n - loaded by data()\n",
"- reproduced using dump(\"mydata\", file = \"\")\n")
code <- readline(paste("have you checked this code in a fresh R
session",
"\n(invoking R with the --vanilla option if
possible)",
"\nand is this code copied to the clipboard?
(y/n) "))
if (no(code))
return(cat("\nIf your query is not directly related to code",
"(e.g. a general query \nabout R's capabilities),",
"email R-help at r-project.org directly. ",
"\nOtherwise prepare some example code first.\n"))
change <- readline(paste("Would you like to change your subject
line:\n",
subject, "\nto something more meaningful?
(y/n) "))
if (yes(change))
subject <- readline("Enter subject: \n")
methods <- c("mailx", "gnudoit", "none", "ess")
method <- if (is.null(method))
"none"
else methods[pmatch(method, methods)]
body <- paste("\\n<<Write your query here, using your example code
to illustrate>>",
"\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
"--please do not edit the information below--\\n\\n",
"Version:\\n ", paste(names(R.version), R.version,
sep = " = ",
collapse = "\\n "), if
(nzchar(Sys.getenv("R_GUI_APP_VERSION")))
paste("\\n\\nGUI:\\n R-GUI ",
Sys.getenv("R_GUI_APP_VERSION"),
" (", Sys.getenv("R_GUI_APP_REVISION"), ")",
sep = "")
else "", "\\n\\n",
"Locale:\\n", Sys.getlocale(), "\\n\\n",
"Search Path:\\n ", paste(search(), collapse = ", "),
"\\n", sep = "", collapse = "")
if (method == "gnudoit") {
cmd <- paste("gnudoit -q '", "(mail nil \"", address,
"\")", "(insert \"", body, "\")",
"(search-backward \"Subject:\")",
"(end-of-line)'", sep = "")
system(cmd)
}
else if (method == "none") {
disclaimer <- paste("# Your mailer is set to \"none\" (default
on Windows),\n",
"# hence we cannot send the help request directly from R.\n",
"# Please copy the help request (after finishing it) to\n",
"# your favorite email program and send it to\n#\n",
"# ", address, "\n#\n",
"######################################################\n",
"\n\n", sep = "")
cat(disclaimer, file = file)
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = TRUE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
cat("The unsent help request can be found in file", file,
"\n")
}
else if (method == "mailx") {
if (missing(subject))
stop("'subject' missing")
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = FALSE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
if (is.character(ccaddress) && nzchar(ccaddress)) {
cmdargs <- paste("-s '", subject, "' -c", ccaddress,
address, "<", file, "2>/dev/null")
}
else cmdargs <- paste("-s '", subject, "'", address,
"<", file, "2>/dev/null")
status <- 1
cat("Submit the help request? ")
answer <- readline()
answer <- grep("y", answer, ignore.case = TRUE)
if (length(answer) > 0) {
cat("Sending email ...\n")
status <- system(paste("mailx", cmdargs))
if (status > 0)
status <- system(paste("Mail", cmdargs))
if (status > 0)
status <- system(paste("/usr/ucb/mail", cmdargs))
if (status == 0)
unlink(file)
else {
cat("Sending email failed!\n")
cat("The unsent help request can be found in file",
file, "\n")
}
}
else cat("The unsent help request can be found in file",
file, "\n")
}
else if (method == "ess") {
body <- gsub("\\\\n", "\n", body)
cat(body)
}
}
-----------------------------------------------------------------------
Gabor Grothendieck wrote:
Here is another update. I have added the following:
- info about using a fresh R session. (In that case ls() output is less
essential; however, the developers of sessionInfo() might consider
adding that as a default or as an option.)
- questioner should consider use of functions.
- for data use dump(x, file = "") to reproducibly display data or use
builtin datasets listed by data()
- minimal versions of slow code should be presented in cases where
questioner is looking for faster code.
- we still need to add links to illustrative sample questions in r-help
The following were not added for the reason cited:
- guide is not just for questioners. Important to distinguish roles
of questioner, responder and reader.
- what is to be provided ought to be given a name to make it easier
to refer to. An unlabelled set of points is too vague. Test
framework seems appropriately descriptive. By giving it a name
one can request that a questioner "provide a test framework as
defined in the posting guide summary".
- self contained is not implied by reproducible. Reproducible
only means that info is available somewhere -- not that its all
available right in the questioner's post and all in a manner that
is readily accessible.
- focus should be on making data minimal. Don't like attachments
since responder must save them and read them in. It encourages
use of large rather than minimal data sets.
Summary
Surprisingly, the main problem for responders is not to answer the
question but to quickly figure out what the question is, reproduce it
in their own R session and test their answer.
Test Framework. To faciliate this provide a test framework of:
(1) minimal reproducible self-contained commented code and data
that has been run in a fresh R session. That means code and
data have been cut down as far as possible to the essentials
needed to illustrate the problem and were run are just after
starting up R. Also it means that its possible for responders
to just copy the code and data section from the questioner's
post to the clipboard and paste it into their session to see
the same output without having to enter even one R command.
In some cases there may be an advantage to present the code as
a function and in the case of needing a speedup be sure to post
a minimal version of the slow code. Use builtin data sets such
as those listed by data() to illustrate problem or reduce your
data to a minimum and present it reproducibly by using:
dump("mydata", file = "")
(2) comments/explanation of what the code is intended to produce
-- Don't assume its obvious!
(3) versions of all software used, e.g. sessionInfo(),
or R.version.string; packageDescription("zoo")$Version
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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Dr H Turner Research Fellow Dept. of Statistics The University of Warwick Coventry CV4 7AL Tel: 024 76575870 Fax: 024 76524532 Url: www.warwick.ac.uk/go/heatherturner
That's an excellent idea. One other item that could be checkable would be if the user has the most recent versions of the packages involved in the query. Perhaps it could display the unupdated packages and ask the user if any of those are involved in the query. Probably needs to give fair warning that it is sending off an email so people don't wind up sending out emails when they are really just trying out the system. Probably "none" should be the default for email so that its not regarded as obnoxious. Might be nice if it used local versions of documents if they exist locally. On Windows they do. Check out ?getRversion On Mon, Jun 9, 2008 at 10:35 AM, Dr Heather Turner
<Heather.Turner at warwick.ac.uk> wrote:
Whilst it is a good idea to improve the posting guide, it seems to me that
it would be useful to have a function along the lines of bug.report(), to
help a potential questioner make sure they have done their homework and have
the relevant information to put into a post to R-help.
Even those of us who know what ought to go into a post can sometimes forget
to check something obvious - I recently got caught out by not checking an
error was reproducible in the patched version for example.
So I have written a help.request() function (see below), which
- prompts the user to check the relevant resources, stopping and opening the
relevant url where necessary
- checks their R version is up-to-date (in a rather messy way - please
suggest improvements!)
- prompts them to prepare appropriate example code and test it in a fresh R
session
- prompts them to give a meaningful subject line
- automatically adds system info to the post (as in bug.report)
- sends the message for them (ensuring a fresh thread is started)
Is this an idea worth taking further? I would be happy to make improvements
as suggested and write a help file if so.
Heather
------------------------------------------------------------
help.request <- function (subject = "",
ccaddress = Sys.getenv("USER"),
method = getOption("mailer"),
address = "r-help at R-project.org",
file = "R.help.request")
{
no <- function(answer) answer == "n"
yes <- function(answer) answer == "y"
go <- function(url) {
cat("Please do this first - the site has been loaded in your web
browser\n")
browseURL(url)
}
cat("Checklist:\n")
post <- readline("Have you read the posting guide? (y/n) ")
if (no(post)) return(go("http://www.r-project.org/posting-guide.html"))
FAQ <- readline("Have you checked the FAQ? (y/n) ")
if (no(FAQ)) return(go("http://cran.r-project.org/faqs.html"))
intro <- readline("Have you checked An Introduction to R? (y/n) ")
if (no(intro))
return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
NEWS <- readline("Have you checked the NEWS of the latest development
release? (y/n) ")
if (no(NEWS)) return(go("https://svn.r-project.org/R/trunk/NEWS"))
rsitesearch <- readline("Have you looked on RSiteSearch? (y/n) ")
if (no(rsitesearch)) {
cat("Please do this first - the site has been loaded in your web
browser\n")
return(RSiteSearch(subject))
}
inf <- sessionInfo()
if ("otherPkgs" %in% names(inf)){
other <- readline("You have packages other than the base packages
loaded.",
"\nIf your query relates to one of these, have you
",
"checked any corresponding books/manuals \nand ",
"considered contacting the package maintainer?
(y/n/NA) ")
if(no(other)) return("Please do this first.")
}
man <- url("http://cran.r-project.org/manuals.html")
ver <- scan(man, what = character(0), sep = "\n", skip = 13, nlines = 1,
quiet = TRUE)
major <- as.numeric(substr(ver, start = 18, stop = 18))
minor <- as.numeric(substr(ver, start = 20, stop = 22))
if (major < as.numeric(R.Version()$major) ||
minor < as.numeric(R.Version()$major)) {
update <- readline("Your R version is out-of-date, would you like to
update now? (y/n) ")
if (yes(update)) {
return(go(getOption("repos")))
}
}
## To get long prompt!
cat("Have you written example code that is\n",
"- minimal\n - reproducible\n - self-contained\n - commented",
"\nusing data that is either\n",
"- constructed by the code\n - loaded by data()\n",
"- reproduced using dump(\"mydata\", file = \"\")\n")
code <- readline(paste("have you checked this code in a fresh R session",
"\n(invoking R with the --vanilla option if
possible)",
"\nand is this code copied to the clipboard? (y/n)
"))
if (no(code))
return(cat("\nIf your query is not directly related to code",
"(e.g. a general query \nabout R's capabilities),",
"email R-help at r-project.org directly. ",
"\nOtherwise prepare some example code first.\n"))
change <- readline(paste("Would you like to change your subject line:\n",
subject, "\nto something more meaningful? (y/n)
"))
if (yes(change))
subject <- readline("Enter subject: \n")
methods <- c("mailx", "gnudoit", "none", "ess")
method <- if (is.null(method))
"none"
else methods[pmatch(method, methods)]
body <- paste("\\n<<Write your query here, using your example code to
illustrate>>",
"\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
"--please do not edit the information below--\\n\\n",
"Version:\\n ", paste(names(R.version), R.version, sep = "
= ",
collapse = "\\n "), if
(nzchar(Sys.getenv("R_GUI_APP_VERSION")))
paste("\\n\\nGUI:\\n R-GUI ",
Sys.getenv("R_GUI_APP_VERSION"),
" (", Sys.getenv("R_GUI_APP_REVISION"), ")",
sep = "")
else "", "\\n\\n", "Locale:\\n",
Sys.getlocale(), "\\n\\n",
"Search Path:\\n ", paste(search(), collapse = ", "),
"\\n", sep = "", collapse = "")
if (method == "gnudoit") {
cmd <- paste("gnudoit -q '", "(mail nil \"", address,
"\")", "(insert \"", body, "\")", "(search-backward
\"Subject:\")",
"(end-of-line)'", sep = "")
system(cmd)
}
else if (method == "none") {
disclaimer <- paste("# Your mailer is set to \"none\" (default on
Windows),\n",
"# hence we cannot send the help request directly from R.\n",
"# Please copy the help request (after finishing it) to\n",
"# your favorite email program and send it to\n#\n",
"# ", address, "\n#\n",
"######################################################\n",
"\n\n", sep = "")
cat(disclaimer, file = file)
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = TRUE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
cat("The unsent help request can be found in file", file,
"\n")
}
else if (method == "mailx") {
if (missing(subject))
stop("'subject' missing")
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = FALSE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
if (is.character(ccaddress) && nzchar(ccaddress)) {
cmdargs <- paste("-s '", subject, "' -c", ccaddress,
address, "<", file, "2>/dev/null")
}
else cmdargs <- paste("-s '", subject, "'", address,
"<", file, "2>/dev/null")
status <- 1
cat("Submit the help request? ")
answer <- readline()
answer <- grep("y", answer, ignore.case = TRUE)
if (length(answer) > 0) {
cat("Sending email ...\n")
status <- system(paste("mailx", cmdargs))
if (status > 0)
status <- system(paste("Mail", cmdargs))
if (status > 0)
status <- system(paste("/usr/ucb/mail", cmdargs))
if (status == 0)
unlink(file)
else {
cat("Sending email failed!\n")
cat("The unsent help request can be found in file",
file, "\n")
}
}
else cat("The unsent help request can be found in file",
file, "\n")
}
else if (method == "ess") {
body <- gsub("\\\\n", "\n", body)
cat(body)
}
}
-----------------------------------------------------------------------
Gabor Grothendieck wrote:
Here is another update. I have added the following:
- info about using a fresh R session. (In that case ls() output is less
essential; however, the developers of sessionInfo() might consider
adding that as a default or as an option.)
- questioner should consider use of functions.
- for data use dump(x, file = "") to reproducibly display data or use
builtin datasets listed by data()
- minimal versions of slow code should be presented in cases where
questioner is looking for faster code.
- we still need to add links to illustrative sample questions in r-help
The following were not added for the reason cited:
- guide is not just for questioners. Important to distinguish roles
of questioner, responder and reader.
- what is to be provided ought to be given a name to make it easier
to refer to. An unlabelled set of points is too vague. Test
framework seems appropriately descriptive. By giving it a name
one can request that a questioner "provide a test framework as
defined in the posting guide summary".
- self contained is not implied by reproducible. Reproducible
only means that info is available somewhere -- not that its all
available right in the questioner's post and all in a manner that
is readily accessible.
- focus should be on making data minimal. Don't like attachments
since responder must save them and read them in. It encourages
use of large rather than minimal data sets.
Summary
Surprisingly, the main problem for responders is not to answer the
question but to quickly figure out what the question is, reproduce it
in their own R session and test their answer.
Test Framework. To faciliate this provide a test framework of:
(1) minimal reproducible self-contained commented code and data
that has been run in a fresh R session. That means code and
data have been cut down as far as possible to the essentials
needed to illustrate the problem and were run are just after
starting up R. Also it means that its possible for responders
to just copy the code and data section from the questioner's
post to the clipboard and paste it into their session to see
the same output without having to enter even one R command.
In some cases there may be an advantage to present the code as
a function and in the case of needing a speedup be sure to post
a minimal version of the slow code. Use builtin data sets such
as those listed by data() to illustrate problem or reduce your
data to a minimum and present it reproducibly by using:
dump("mydata", file = "")
(2) comments/explanation of what the code is intended to produce
-- Don't assume its obvious!
(3) versions of all software used, e.g. sessionInfo(),
or R.version.string; packageDescription("zoo")$Version
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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
-- Dr H Turner Research Fellow Dept. of Statistics The University of Warwick Coventry CV4 7AL Tel: 024 76575870 Fax: 024 76524532 Url: www.warwick.ac.uk/go/heatherturner
Thanks for the helpful tips and suggestions, I'll work them in. You get local versions of the documents on Unix too - RShowDoc() will do the trick. I'll post an updated version in due course, Heather
Gabor Grothendieck wrote:
That's an excellent idea. One other item that could be checkable would be if the user has the most recent versions of the packages involved in the query. Perhaps it could display the unupdated packages and ask the user if any of those are involved in the query. Probably needs to give fair warning that it is sending off an email so people don't wind up sending out emails when they are really just trying out the system. Probably "none" should be the default for email so that its not regarded as obnoxious. Might be nice if it used local versions of documents if they exist locally. On Windows they do. Check out ?getRversion On Mon, Jun 9, 2008 at 10:35 AM, Dr Heather Turner <Heather.Turner at warwick.ac.uk> wrote:
Whilst it is a good idea to improve the posting guide, it seems to me that
it would be useful to have a function along the lines of bug.report(), to
help a potential questioner make sure they have done their homework and have
the relevant information to put into a post to R-help.
Even those of us who know what ought to go into a post can sometimes forget
to check something obvious - I recently got caught out by not checking an
error was reproducible in the patched version for example.
So I have written a help.request() function (see below), which
- prompts the user to check the relevant resources, stopping and opening the
relevant url where necessary
- checks their R version is up-to-date (in a rather messy way - please
suggest improvements!)
- prompts them to prepare appropriate example code and test it in a fresh R
session
- prompts them to give a meaningful subject line
- automatically adds system info to the post (as in bug.report)
- sends the message for them (ensuring a fresh thread is started)
Is this an idea worth taking further? I would be happy to make improvements
as suggested and write a help file if so.
Heather
------------------------------------------------------------
help.request <- function (subject = "",
ccaddress = Sys.getenv("USER"),
method = getOption("mailer"),
address = "r-help at R-project.org",
file = "R.help.request")
{
no <- function(answer) answer == "n"
yes <- function(answer) answer == "y"
go <- function(url) {
cat("Please do this first - the site has been loaded in your web
browser\n")
browseURL(url)
}
cat("Checklist:\n")
post <- readline("Have you read the posting guide? (y/n) ")
if (no(post)) return(go("http://www.r-project.org/posting-guide.html"))
FAQ <- readline("Have you checked the FAQ? (y/n) ")
if (no(FAQ)) return(go("http://cran.r-project.org/faqs.html"))
intro <- readline("Have you checked An Introduction to R? (y/n) ")
if (no(intro))
return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
NEWS <- readline("Have you checked the NEWS of the latest development
release? (y/n) ")
if (no(NEWS)) return(go("https://svn.r-project.org/R/trunk/NEWS"))
rsitesearch <- readline("Have you looked on RSiteSearch? (y/n) ")
if (no(rsitesearch)) {
cat("Please do this first - the site has been loaded in your web
browser\n")
return(RSiteSearch(subject))
}
inf <- sessionInfo()
if ("otherPkgs" %in% names(inf)){
other <- readline("You have packages other than the base packages
loaded.",
"\nIf your query relates to one of these, have you
",
"checked any corresponding books/manuals \nand ",
"considered contacting the package maintainer?
(y/n/NA) ")
if(no(other)) return("Please do this first.")
}
man <- url("http://cran.r-project.org/manuals.html")
ver <- scan(man, what = character(0), sep = "\n", skip = 13, nlines = 1,
quiet = TRUE)
major <- as.numeric(substr(ver, start = 18, stop = 18))
minor <- as.numeric(substr(ver, start = 20, stop = 22))
if (major < as.numeric(R.Version()$major) ||
minor < as.numeric(R.Version()$major)) {
update <- readline("Your R version is out-of-date, would you like to
update now? (y/n) ")
if (yes(update)) {
return(go(getOption("repos")))
}
}
## To get long prompt!
cat("Have you written example code that is\n",
"- minimal\n - reproducible\n - self-contained\n - commented",
"\nusing data that is either\n",
"- constructed by the code\n - loaded by data()\n",
"- reproduced using dump(\"mydata\", file = \"\")\n")
code <- readline(paste("have you checked this code in a fresh R session",
"\n(invoking R with the --vanilla option if
possible)",
"\nand is this code copied to the clipboard? (y/n)
"))
if (no(code))
return(cat("\nIf your query is not directly related to code",
"(e.g. a general query \nabout R's capabilities),",
"email R-help at r-project.org directly. ",
"\nOtherwise prepare some example code first.\n"))
change <- readline(paste("Would you like to change your subject line:\n",
subject, "\nto something more meaningful? (y/n)
"))
if (yes(change))
subject <- readline("Enter subject: \n")
methods <- c("mailx", "gnudoit", "none", "ess")
method <- if (is.null(method))
"none"
else methods[pmatch(method, methods)]
body <- paste("\\n<<Write your query here, using your example code to
illustrate>>",
"\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
"--please do not edit the information below--\\n\\n",
"Version:\\n ", paste(names(R.version), R.version, sep = "
= ",
collapse = "\\n "), if
(nzchar(Sys.getenv("R_GUI_APP_VERSION")))
paste("\\n\\nGUI:\\n R-GUI ",
Sys.getenv("R_GUI_APP_VERSION"),
" (", Sys.getenv("R_GUI_APP_REVISION"), ")",
sep = "")
else "", "\\n\\n", "Locale:\\n",
Sys.getlocale(), "\\n\\n",
"Search Path:\\n ", paste(search(), collapse = ", "),
"\\n", sep = "", collapse = "")
if (method == "gnudoit") {
cmd <- paste("gnudoit -q '", "(mail nil \"", address,
"\")", "(insert \"", body, "\")", "(search-backward
\"Subject:\")",
"(end-of-line)'", sep = "")
system(cmd)
}
else if (method == "none") {
disclaimer <- paste("# Your mailer is set to \"none\" (default on
Windows),\n",
"# hence we cannot send the help request directly from R.\n",
"# Please copy the help request (after finishing it) to\n",
"# your favorite email program and send it to\n#\n",
"# ", address, "\n#\n",
"######################################################\n",
"\n\n", sep = "")
cat(disclaimer, file = file)
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = TRUE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
cat("The unsent help request can be found in file", file,
"\n")
}
else if (method == "mailx") {
if (missing(subject))
stop("'subject' missing")
body <- gsub("\\\\n", "\n", body)
cat(body, file = file, append = FALSE)
cat("Please edit the help request.\n")
system(paste(getOption("editor"), file))
if (is.character(ccaddress) && nzchar(ccaddress)) {
cmdargs <- paste("-s '", subject, "' -c", ccaddress,
address, "<", file, "2>/dev/null")
}
else cmdargs <- paste("-s '", subject, "'", address,
"<", file, "2>/dev/null")
status <- 1
cat("Submit the help request? ")
answer <- readline()
answer <- grep("y", answer, ignore.case = TRUE)
if (length(answer) > 0) {
cat("Sending email ...\n")
status <- system(paste("mailx", cmdargs))
if (status > 0)
status <- system(paste("Mail", cmdargs))
if (status > 0)
status <- system(paste("/usr/ucb/mail", cmdargs))
if (status == 0)
unlink(file)
else {
cat("Sending email failed!\n")
cat("The unsent help request can be found in file",
file, "\n")
}
}
else cat("The unsent help request can be found in file",
file, "\n")
}
else if (method == "ess") {
body <- gsub("\\\\n", "\n", body)
cat(body)
}
}
-----------------------------------------------------------------------
Gabor Grothendieck wrote:
Here is another update. I have added the following:
- info about using a fresh R session. (In that case ls() output is less
essential; however, the developers of sessionInfo() might consider
adding that as a default or as an option.)
- questioner should consider use of functions.
- for data use dump(x, file = "") to reproducibly display data or use
builtin datasets listed by data()
- minimal versions of slow code should be presented in cases where
questioner is looking for faster code.
- we still need to add links to illustrative sample questions in r-help
The following were not added for the reason cited:
- guide is not just for questioners. Important to distinguish roles
of questioner, responder and reader.
- what is to be provided ought to be given a name to make it easier
to refer to. An unlabelled set of points is too vague. Test
framework seems appropriately descriptive. By giving it a name
one can request that a questioner "provide a test framework as
defined in the posting guide summary".
- self contained is not implied by reproducible. Reproducible
only means that info is available somewhere -- not that its all
available right in the questioner's post and all in a manner that
is readily accessible.
- focus should be on making data minimal. Don't like attachments
since responder must save them and read them in. It encourages
use of large rather than minimal data sets.
Summary
Surprisingly, the main problem for responders is not to answer the
question but to quickly figure out what the question is, reproduce it
in their own R session and test their answer.
Test Framework. To faciliate this provide a test framework of:
(1) minimal reproducible self-contained commented code and data
that has been run in a fresh R session. That means code and
data have been cut down as far as possible to the essentials
needed to illustrate the problem and were run are just after
starting up R. Also it means that its possible for responders
to just copy the code and data section from the questioner's
post to the clipboard and paste it into their session to see
the same output without having to enter even one R command.
In some cases there may be an advantage to present the code as
a function and in the case of needing a speedup be sure to post
a minimal version of the slow code. Use builtin data sets such
as those listed by data() to illustrate problem or reduce your
data to a minimum and present it reproducibly by using:
dump("mydata", file = "")
(2) comments/explanation of what the code is intended to produce
-- Don't assume its obvious!
(3) versions of all software used, e.g. sessionInfo(),
or R.version.string; packageDescription("zoo")$Version
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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
<ggrothendieck at gmail.com> wrote:
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 ...
______________________________________________ R-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
-- Dr H Turner Research Fellow Dept. of Statistics The University of Warwick Coventry CV4 7AL Tel: 024 76575870 Fax: 024 76524532 Url: www.warwick.ac.uk/go/heatherturner
Dr H Turner Research Fellow Dept. of Statistics The University of Warwick Coventry CV4 7AL Tel: 024 76575870 Fax: 024 76524532 Url: www.warwick.ac.uk/go/heatherturner
"HT" == Heather Turner <Heather.Turner at warwick.ac.uk>
on Mon, 09 Jun 2008 17:21:17 +0100 writes:
HT> Thanks for the helpful tips and suggestions, I'll work
HT> them in. You get local versions of the documents on Unix
HT> too - RShowDoc() will do the trick.
HT> I'll post an updated version in due course,
Thank you, Heather and Gabor (and the other contributors).
Indeed, I too like the idea of providing a new R function for
this.
Ideally, Heather, you'd try to "factor out" some of the common
functionality of bug.report() and help.request() into a few
utils-namespace hidden auxiliary functions.
Ideally, you'd attach text/plain attachments (base64 encoded) so
there won't be line wrap arounds.
Martin
HT> Gabor Grothendieck wrote:
>> That's an excellent idea.
>>
>> One other item that could be checkable would be if the
>> user has the most recent versions of the packages
>> involved in the query. Perhaps it could display the
>> unupdated packages and ask the user if any of those are
>> involved in the query.
>>
>> Probably needs to give fair warning that it is sending
>> off an email so people don't wind up sending out emails
>> when they are really just trying out the system.
>> Probably "none" should be the default for email so that
>> its not regarded as obnoxious.
>>
>> Might be nice if it used local versions of documents if
>> they exist locally. On Windows they do.
>>
>> Check out ?getRversion
>>
>> On Mon, Jun 9, 2008 at 10:35 AM, Dr Heather Turner
>> <Heather.Turner at warwick.ac.uk> wrote:
>>> Whilst it is a good idea to improve the posting guide,
>>> it seems to me that it would be useful to have a
>>> function along the lines of bug.report(), to help a
>>> potential questioner make sure they have done their
>>> homework and have the relevant information to put into a
>>> post to R-help.
>>>
>>> Even those of us who know what ought to go into a post
>>> can sometimes forget to check something obvious - I
>>> recently got caught out by not checking an error was
>>> reproducible in the patched version for example.
>>>
>>> So I have written a help.request() function (see below),
>>> which - prompts the user to check the relevant
>>> resources, stopping and opening the relevant url where
>>> necessary - checks their R version is up-to-date (in a
>>> rather messy way - please suggest improvements!) -
>>> prompts them to prepare appropriate example code and
>>> test it in a fresh R session - prompts them to give a
>>> meaningful subject line - automatically adds system info
>>> to the post (as in bug.report) - sends the message for
>>> them (ensuring a fresh thread is started)
>>>
>>> Is this an idea worth taking further? I would be happy
>>> to make improvements as suggested and write a help file
>>> if so.
>>>
>>> Heather
>>>
>>> ------------------------------------------------------------
>>>
>>> help.request <- function (subject = "", ccaddress =
>>> Sys.getenv("USER"), method = getOption("mailer"),
>>> address = "r-help at R-project.org", file =
>>> "R.help.request") { no <- function(answer) answer == "n"
>>> yes <- function(answer) answer == "y" go <-
>>> function(url) { cat("Please do this first - the site has
>>> been loaded in your web browser\n") browseURL(url) }
>>> cat("Checklist:\n") post <- readline("Have you read the
>>> posting guide? (y/n) ") if (no(post))
>>> return(go("http://www.r-project.org/posting-guide.html"))
>>> FAQ <- readline("Have you checked the FAQ? (y/n) ") if
>>> (no(FAQ))
>>> return(go("http://cran.r-project.org/faqs.html")) intro
>>> <- readline("Have you checked An Introduction to R?
>>> (y/n) ") if (no(intro))
>>> return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
>>> NEWS <- readline("Have you checked the NEWS of the
>>> latest development release? (y/n) ") if (no(NEWS))
>>> return(go("https://svn.r-project.org/R/trunk/NEWS"))
>>> rsitesearch <- readline("Have you looked on RSiteSearch?
>>> (y/n) ") if (no(rsitesearch)) { cat("Please do this
>>> first - the site has been loaded in your web browser\n")
>>> return(RSiteSearch(subject)) } inf <- sessionInfo() if
>>> ("otherPkgs" %in% names(inf)){ other <- readline("You
>>> have packages other than the base packages loaded.",
>>> "\nIf your query relates to one of these, have you ",
>>> "checked any corresponding books/manuals \nand ",
>>> "considered contacting the package maintainer? (y/n/NA)
>>> ") if(no(other)) return("Please do this first.") }
>>>
>>> man <- url("http://cran.r-project.org/manuals.html") ver
>>> <- scan(man, what = character(0), sep = "\n", skip = 13,
>>> nlines = 1, quiet = TRUE) major <-
>>> as.numeric(substr(ver, start = 18, stop = 18)) minor <-
>>> as.numeric(substr(ver, start = 20, stop = 22)) if (major
>>> < as.numeric(R.Version()$major) || minor <
>>> as.numeric(R.Version()$major)) { update <-
>>> readline("Your R version is out-of-date, would you like
>>> to update now? (y/n) ") if (yes(update)) {
>>> return(go(getOption("repos"))) } } ## To get long
>>> prompt! cat("Have you written example code that is\n",
>>> "- minimal\n - reproducible\n - self-contained\n -
>>> commented", "\nusing data that is either\n", "-
>>> constructed by the code\n - loaded by data()\n", "-
>>> reproduced using dump(\"mydata\", file = \"\")\n") code
>>> <- readline(paste("have you checked this code in a fresh
>>> R session", "\n(invoking R with the --vanilla option if
>>> possible)", "\nand is this code copied to the clipboard?
>>> (y/n) ")) if (no(code)) return(cat("\nIf your query is
>>> not directly related to code", "(e.g. a general query
>>> \nabout R's capabilities),", "email R-help at r-project.org
>>> directly. ", "\nOtherwise prepare some example code
>>> first.\n")) change <- readline(paste("Would you like to
>>> change your subject line:\n", subject, "\nto something
>>> more meaningful? (y/n) ")) if (yes(change)) subject <-
>>> readline("Enter subject: \n")
>>>
>>> methods <- c("mailx", "gnudoit", "none", "ess") method
>>> <- if (is.null(method)) "none" else
>>> methods[pmatch(method, methods)] body <-
>>> paste("\\n<<Write your query here, using your example
>>> code to
illustrate> ",
>>> "\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
>>> "--please do not edit the information below--\\n\\n",
>>> "Version:\\n ", paste(names(R.version), R.version, sep =
>>> " = ", collapse = "\\n "), if
>>> (nzchar(Sys.getenv("R_GUI_APP_VERSION")))
>>> paste("\\n\\nGUI:\\n R-GUI ",
>>> Sys.getenv("R_GUI_APP_VERSION"), " (",
>>> Sys.getenv("R_GUI_APP_REVISION"), ")", sep = "") else
>>> "", "\\n\\n", "Locale:\\n", Sys.getlocale(), "\\n\\n",
>>> "Search Path:\\n ", paste(search(), collapse = ", "),
>>> "\\n", sep = "", collapse = "") if (method == "gnudoit")
>>> { cmd <- paste("gnudoit -q '", "(mail nil \"", address,
>>> "\")", "(insert \"", body, "\")", "(search-backward
>>> \"Subject:\")", "(end-of-line)'", sep = "") system(cmd)
>>> } else if (method == "none") { disclaimer <- paste("#
>>> Your mailer is set to \"none\" (default on Windows),\n",
>>> "# hence we cannot send the help request directly from
>>> R.\n", "# Please copy the help request (after finishing
>>> it) to\n", "# your favorite email program and send it
>>> to\n#\n", "# ", address, "\n#\n",
>>> "######################################################\n",
>>> "\n\n", sep = "") cat(disclaimer, file = file) body <-
>>> gsub("\\\\n", "\n", body) cat(body, file = file, append
>>> = TRUE) cat("Please edit the help request.\n")
>>> system(paste(getOption("editor"), file)) cat("The unsent
>>> help request can be found in file", file, "\n") } else
>>> if (method == "mailx") { if (missing(subject))
>>> stop("'subject' missing") body <- gsub("\\\\n", "\n",
>>> body) cat(body, file = file, append = FALSE) cat("Please
>>> edit the help request.\n")
>>> system(paste(getOption("editor"), file)) if
>>> (is.character(ccaddress) && nzchar(ccaddress)) { cmdargs
>>> <- paste("-s '", subject, "' -c", ccaddress, address,
>>> "<", file, "2>/dev/null") } else cmdargs <- paste("-s
>>> '", subject, "'", address, "<", file, "2>/dev/null")
>>> status <- 1 cat("Submit the help request? ") answer <-
>>> readline() answer <- grep("y", answer, ignore.case =
>>> TRUE) if (length(answer) > 0) { cat("Sending email
>>> ...\n") status <- system(paste("mailx", cmdargs)) if
>>> (status > 0) status <- system(paste("Mail", cmdargs)) if
>>> (status > 0) status <- system(paste("/usr/ucb/mail",
>>> cmdargs)) if (status == 0) unlink(file) else {
>>> cat("Sending email failed!\n") cat("The unsent help
>>> request can be found in file", file, "\n") } } else
>>> cat("The unsent help request can be found in file",
>>> file, "\n") } else if (method == "ess") { body <-
>>> gsub("\\\\n", "\n", body) cat(body) } }
>>>
>>> -----------------------------------------------------------------------
>>>
>>> Gabor Grothendieck wrote:
>>>> Here is another update. I have added the following:
>>>>
>>>> - info about using a fresh R session. (In that case
>>>> ls() output is less essential; however, the developers
>>>> of sessionInfo() might consider adding that as a
>>>> default or as an option.)
>>>>
>>>> - questioner should consider use of functions.
>>>>
>>>> - for data use dump(x, file = "") to reproducibly
>>>> display data or use builtin datasets listed by data()
>>>>
>>>> - minimal versions of slow code should be presented in
>>>> cases where questioner is looking for faster code.
>>>>
>>>> - we still need to add links to illustrative sample
>>>> questions in r-help
>>>>
>>>> The following were not added for the reason cited:
>>>>
>>>> - guide is not just for questioners. Important to
>>>> distinguish roles of questioner, responder and reader.
>>>>
>>>> - what is to be provided ought to be given a name to
>>>> make it easier to refer to. An unlabelled set of
>>>> points is too vague. Test framework seems
>>>> appropriately descriptive. By giving it a name one can
>>>> request that a questioner "provide a test framework as
>>>> defined in the posting guide summary".
>>>>
>>>> - self contained is not implied by reproducible.
>>>> Reproducible only means that info is available
>>>> somewhere -- not that its all available right in the
>>>> questioner's post and all in a manner that is readily
>>>> accessible.
>>>>
>>>> - focus should be on making data minimal. Don't like
>>>> attachments since responder must save them and read
>>>> them in. It encourages use of large rather than
>>>> minimal data sets.
>>>>
>>>> Summary
>>>>
>>>> Surprisingly, the main problem for responders is not to
>>>> answer the question but to quickly figure out what the
>>>> question is, reproduce it in their own R session and
>>>> test their answer.
>>>>
>>>> Test Framework. To faciliate this provide a test
>>>> framework of:
>>>>
>>>> (1) minimal reproducible self-contained commented code
>>>> and data that has been run in a fresh R session. That
>>>> means code and data have been cut down as far as
>>>> possible to the essentials needed to illustrate the
>>>> problem and were run are just after starting up R.
>>>> Also it means that its possible for responders to just
>>>> copy the code and data section from the questioner's
>>>> post to the clipboard and paste it into their session
>>>> to see the same output without having to enter even one
>>>> R command. In some cases there may be an advantage to
>>>> present the code as a function and in the case of
>>>> needing a speedup be sure to post a minimal version of
>>>> the slow code. Use builtin data sets such as those
>>>> listed by data() to illustrate problem or reduce your
>>>> data to a minimum and present it reproducibly by using:
>>>> dump("mydata", file = "")
>>>>
>>>> (2) comments/explanation of what the code is intended
>>>> to produce -- Don't assume its obvious!
>>>>
>>>> (3) versions of all software used, e.g. sessionInfo(),
>>>> or R.version.string; packageDescription("zoo")$Version
>>>>
>>>> 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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
>>>> <ggrothendieck at gmail.com> wrote:
>>>>> 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 ...
>>>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> --
>>> Dr H Turner Research Fellow Dept. of Statistics The
>>> University of Warwick Coventry CV4 7AL
>>>
>>> Tel: 024 76575870 Fax: 024 76524532 Url:
>>> www.warwick.ac.uk/go/heatherturner
>>>
Dr H Turner
HT> Research Fellow Dept. of Statistics The University of
HT> Warwick Coventry CV4 7AL
HT> Tel: 024 76575870 Fax: 024 76524532 Url:
HT> www.warwick.ac.uk/go/heatherturner
HT> ______________________________________________
HT> R-devel at r-project.org mailing list
HT> https://stat.ethz.ch/mailman/listinfo/r-devel
1 day later
Okay, here's the update.
I've created a new function create.post() (with Windows and Unix
versions) which would be the internal function that creates the post
template ready to edit and optionally send. In the Windows version I've
added an experimental method == "mailto" option, which will open the
post template in the default mailer (e.g. Outlook) ready to edit and
post. Maybe a Unix version would also be nice, e.g.
browseURL("mailto:r-bugs at r-project.org?subject=my bug&body=%0A<<insert
bug report here>>%0A%0A%0A%0A--please do not edit the information
below--%0A%0AVersion:%0A platform = x86_64-unknown-linux-gnu%0A ...")
would open the post template in e.g. Thunderbird, but has the side
effect of opening an empty page in the web browser. I don't know if
there's a neater solution?
The create.post() function is basically the old bug.report() with two
extra arguments: 'description' (e.g. "bug report") and 'instructions'
(e.g. "\\n<<Type your message here>>\\n") for customization. It could be
used directly e.g to post to R-devel with session information.
The new bug.report() simply calls create.post() with the appropriate
arguments.
The improved help-request() function calls create.post() after running
through the checks described before.
In response to Gabor's comments, help.request():
- now checks packages are up-to-date and gives option to update
on-the-fly (user may not know whether involved in query, so check all)
- keeps default mailing options as in old bug.report() but
create.post() gives clearer message ("Email the post now?\n (yes/no)")
requiring definite response ("yes" vs "y")
- still uses online documents because some are only available online
(R Site Search, posting guide), it ensures the most up-to-date
documentation is used, and it allows direction to global FAQ page,
avoiding need to check whether user is on Windows/Mac
- uses more robust method of checking R version is up-to-date
I've also written a help file for help.request() which includes the
method="mailto" option. The help file for bug.report would need updating
if this option was kept.
Best wishes,
Heather
Martin Maechler wrote:
>>>>> "HT" == Heather Turner <Heather.Turner at warwick.ac.uk> >>>>> on Mon, 09 Jun 2008 17:21:17 +0100 writes:
HT> Thanks for the helpful tips and suggestions, I'll work
HT> them in. You get local versions of the documents on Unix
HT> too - RShowDoc() will do the trick.
HT> I'll post an updated version in due course,
Thank you, Heather and Gabor (and the other contributors).
Indeed, I too like the idea of providing a new R function for
this.
Ideally, Heather, you'd try to "factor out" some of the common
functionality of bug.report() and help.request() into a few
utils-namespace hidden auxiliary functions.
Ideally, you'd attach text/plain attachments (base64 encoded) so
there won't be line wrap arounds.
Martin
HT> Gabor Grothendieck wrote:
>> That's an excellent idea.
>>
>> One other item that could be checkable would be if the
>> user has the most recent versions of the packages
>> involved in the query. Perhaps it could display the
>> unupdated packages and ask the user if any of those are
>> involved in the query.
>>
>> Probably needs to give fair warning that it is sending
>> off an email so people don't wind up sending out emails
>> when they are really just trying out the system.
>> Probably "none" should be the default for email so that
>> its not regarded as obnoxious.
>>
>> Might be nice if it used local versions of documents if
>> they exist locally. On Windows they do.
>>
>> Check out ?getRversion
>>
>> On Mon, Jun 9, 2008 at 10:35 AM, Dr Heather Turner
>> <Heather.Turner at warwick.ac.uk> wrote:
>>> Whilst it is a good idea to improve the posting guide,
>>> it seems to me that it would be useful to have a
>>> function along the lines of bug.report(), to help a
>>> potential questioner make sure they have done their
>>> homework and have the relevant information to put into a
>>> post to R-help.
>>>
>>> Even those of us who know what ought to go into a post
>>> can sometimes forget to check something obvious - I
>>> recently got caught out by not checking an error was
>>> reproducible in the patched version for example.
>>>
>>> So I have written a help.request() function (see below),
>>> which - prompts the user to check the relevant
>>> resources, stopping and opening the relevant url where
>>> necessary - checks their R version is up-to-date (in a
>>> rather messy way - please suggest improvements!) -
>>> prompts them to prepare appropriate example code and
>>> test it in a fresh R session - prompts them to give a
>>> meaningful subject line - automatically adds system info
>>> to the post (as in bug.report) - sends the message for
>>> them (ensuring a fresh thread is started)
>>>
>>> Is this an idea worth taking further? I would be happy
>>> to make improvements as suggested and write a help file
>>> if so.
>>>
>>> Heather
>>>
>>> ------------------------------------------------------------
>>>
>>> help.request <- function (subject = "", ccaddress =
>>> Sys.getenv("USER"), method = getOption("mailer"),
>>> address = "r-help at R-project.org", file =
>>> "R.help.request") { no <- function(answer) answer == "n"
>>> yes <- function(answer) answer == "y" go <-
>>> function(url) { cat("Please do this first - the site has
>>> been loaded in your web browser\n") browseURL(url) }
>>> cat("Checklist:\n") post <- readline("Have you read the
>>> posting guide? (y/n) ") if (no(post))
>>> return(go("http://www.r-project.org/posting-guide.html"))
>>> FAQ <- readline("Have you checked the FAQ? (y/n) ") if
>>> (no(FAQ))
>>> return(go("http://cran.r-project.org/faqs.html")) intro
>>> <- readline("Have you checked An Introduction to R?
>>> (y/n) ") if (no(intro))
>>> return(go("http://cran.r-project.org/doc/manuals/R-intro.html"))
>>> NEWS <- readline("Have you checked the NEWS of the
>>> latest development release? (y/n) ") if (no(NEWS))
>>> return(go("https://svn.r-project.org/R/trunk/NEWS"))
>>> rsitesearch <- readline("Have you looked on RSiteSearch?
>>> (y/n) ") if (no(rsitesearch)) { cat("Please do this
>>> first - the site has been loaded in your web browser\n")
>>> return(RSiteSearch(subject)) } inf <- sessionInfo() if
>>> ("otherPkgs" %in% names(inf)){ other <- readline("You
>>> have packages other than the base packages loaded.",
>>> "\nIf your query relates to one of these, have you ",
>>> "checked any corresponding books/manuals \nand ",
>>> "considered contacting the package maintainer? (y/n/NA)
>>> ") if(no(other)) return("Please do this first.") }
>>>
>>> man <- url("http://cran.r-project.org/manuals.html") ver
>>> <- scan(man, what = character(0), sep = "\n", skip = 13,
>>> nlines = 1, quiet = TRUE) major <-
>>> as.numeric(substr(ver, start = 18, stop = 18)) minor <-
>>> as.numeric(substr(ver, start = 20, stop = 22)) if (major
>>> < as.numeric(R.Version()$major) || minor <
>>> as.numeric(R.Version()$major)) { update <-
>>> readline("Your R version is out-of-date, would you like
>>> to update now? (y/n) ") if (yes(update)) {
>>> return(go(getOption("repos"))) } } ## To get long
>>> prompt! cat("Have you written example code that is\n",
>>> "- minimal\n - reproducible\n - self-contained\n -
>>> commented", "\nusing data that is either\n", "-
>>> constructed by the code\n - loaded by data()\n", "-
>>> reproduced using dump(\"mydata\", file = \"\")\n") code
>>> <- readline(paste("have you checked this code in a fresh
>>> R session", "\n(invoking R with the --vanilla option if
>>> possible)", "\nand is this code copied to the clipboard?
>>> (y/n) ")) if (no(code)) return(cat("\nIf your query is
>>> not directly related to code", "(e.g. a general query
>>> \nabout R's capabilities),", "email R-help at r-project.org
>>> directly. ", "\nOtherwise prepare some example code
>>> first.\n")) change <- readline(paste("Would you like to
>>> change your subject line:\n", subject, "\nto something
>>> more meaningful? (y/n) ")) if (yes(change)) subject <-
>>> readline("Enter subject: \n")
>>>
>>> methods <- c("mailx", "gnudoit", "none", "ess") method
>>> <- if (is.null(method)) "none" else
>>> methods[pmatch(method, methods)] body <-
>>> paste("\\n<<Write your query here, using your example
>>> code to
illustrate> ",
>>> "\\n<<End with your name and affiliation>>\\n\\n\\n\\n",
>>> "--please do not edit the information below--\\n\\n",
>>> "Version:\\n ", paste(names(R.version), R.version, sep =
>>> " = ", collapse = "\\n "), if
>>> (nzchar(Sys.getenv("R_GUI_APP_VERSION")))
>>> paste("\\n\\nGUI:\\n R-GUI ",
>>> Sys.getenv("R_GUI_APP_VERSION"), " (",
>>> Sys.getenv("R_GUI_APP_REVISION"), ")", sep = "") else
>>> "", "\\n\\n", "Locale:\\n", Sys.getlocale(), "\\n\\n",
>>> "Search Path:\\n ", paste(search(), collapse = ", "),
>>> "\\n", sep = "", collapse = "") if (method == "gnudoit")
>>> { cmd <- paste("gnudoit -q '", "(mail nil \"", address,
>>> "\")", "(insert \"", body, "\")", "(search-backward
>>> \"Subject:\")", "(end-of-line)'", sep = "") system(cmd)
>>> } else if (method == "none") { disclaimer <- paste("#
>>> Your mailer is set to \"none\" (default on Windows),\n",
>>> "# hence we cannot send the help request directly from
>>> R.\n", "# Please copy the help request (after finishing
>>> it) to\n", "# your favorite email program and send it
>>> to\n#\n", "# ", address, "\n#\n",
>>> "######################################################\n",
>>> "\n\n", sep = "") cat(disclaimer, file = file) body <-
>>> gsub("\\\\n", "\n", body) cat(body, file = file, append
>>> = TRUE) cat("Please edit the help request.\n")
>>> system(paste(getOption("editor"), file)) cat("The unsent
>>> help request can be found in file", file, "\n") } else
>>> if (method == "mailx") { if (missing(subject))
>>> stop("'subject' missing") body <- gsub("\\\\n", "\n",
>>> body) cat(body, file = file, append = FALSE) cat("Please
>>> edit the help request.\n")
>>> system(paste(getOption("editor"), file)) if
>>> (is.character(ccaddress) && nzchar(ccaddress)) { cmdargs
>>> <- paste("-s '", subject, "' -c", ccaddress, address,
>>> "<", file, "2>/dev/null") } else cmdargs <- paste("-s
>>> '", subject, "'", address, "<", file, "2>/dev/null")
>>> status <- 1 cat("Submit the help request? ") answer <-
>>> readline() answer <- grep("y", answer, ignore.case =
>>> TRUE) if (length(answer) > 0) { cat("Sending email
>>> ...\n") status <- system(paste("mailx", cmdargs)) if
>>> (status > 0) status <- system(paste("Mail", cmdargs)) if
>>> (status > 0) status <- system(paste("/usr/ucb/mail",
>>> cmdargs)) if (status == 0) unlink(file) else {
>>> cat("Sending email failed!\n") cat("The unsent help
>>> request can be found in file", file, "\n") } } else
>>> cat("The unsent help request can be found in file",
>>> file, "\n") } else if (method == "ess") { body <-
>>> gsub("\\\\n", "\n", body) cat(body) } }
>>>
>>>
-----------------------------------------------------------------------
>>>
>>> Gabor Grothendieck wrote:
>>>> Here is another update. I have added the following:
>>>>
>>>> - info about using a fresh R session. (In that case
>>>> ls() output is less essential; however, the developers
>>>> of sessionInfo() might consider adding that as a
>>>> default or as an option.)
>>>>
>>>> - questioner should consider use of functions.
>>>>
>>>> - for data use dump(x, file = "") to reproducibly
>>>> display data or use builtin datasets listed by data()
>>>>
>>>> - minimal versions of slow code should be presented in
>>>> cases where questioner is looking for faster code.
>>>>
>>>> - we still need to add links to illustrative sample
>>>> questions in r-help
>>>>
>>>> The following were not added for the reason cited:
>>>>
>>>> - guide is not just for questioners. Important to
>>>> distinguish roles of questioner, responder and reader.
>>>>
>>>> - what is to be provided ought to be given a name to
>>>> make it easier to refer to. An unlabelled set of
>>>> points is too vague. Test framework seems
>>>> appropriately descriptive. By giving it a name one can
>>>> request that a questioner "provide a test framework as
>>>> defined in the posting guide summary".
>>>>
>>>> - self contained is not implied by reproducible.
>>>> Reproducible only means that info is available
>>>> somewhere -- not that its all available right in the
>>>> questioner's post and all in a manner that is readily
>>>> accessible.
>>>>
>>>> - focus should be on making data minimal. Don't like
>>>> attachments since responder must save them and read
>>>> them in. It encourages use of large rather than
>>>> minimal data sets.
>>>>
>>>> Summary
>>>>
>>>> Surprisingly, the main problem for responders is not to
>>>> answer the question but to quickly figure out what the
>>>> question is, reproduce it in their own R session and
>>>> test their answer.
>>>>
>>>> Test Framework. To faciliate this provide a test
>>>> framework of:
>>>>
>>>> (1) minimal reproducible self-contained commented code
>>>> and data that has been run in a fresh R session. That
>>>> means code and data have been cut down as far as
>>>> possible to the essentials needed to illustrate the
>>>> problem and were run are just after starting up R.
>>>> Also it means that its possible for responders to just
>>>> copy the code and data section from the questioner's
>>>> post to the clipboard and paste it into their session
>>>> to see the same output without having to enter even one
>>>> R command. In some cases there may be an advantage to
>>>> present the code as a function and in the case of
>>>> needing a speedup be sure to post a minimal version of
>>>> the slow code. Use builtin data sets such as those
>>>> listed by data() to illustrate problem or reduce your
>>>> data to a minimum and present it reproducibly by using:
>>>> dump("mydata", file = "")
>>>>
>>>> (2) comments/explanation of what the code is intended
>>>> to produce -- Don't assume its obvious!
>>>>
>>>> (3) versions of all software used, e.g. sessionInfo(),
>>>> or R.version.string; packageDescription("zoo")$Version
>>>>
>>>> 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 Sat, Jun 7, 2008 at 9:38 AM, Gabor Grothendieck
>>>> <ggrothendieck at gmail.com> wrote:
>>>>> 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 ...
>>>>>>
>>>> ______________________________________________
>>>> R-devel at r-project.org mailing list
>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>> --
>>> Dr H Turner Research Fellow Dept. of Statistics The
>>> University of Warwick Coventry CV4 7AL
>>>
>>> Tel: 024 76575870 Fax: 024 76524532 Url:
>>> www.warwick.ac.uk/go/heatherturner
>>>
--
Dr H Turner
HT> Research Fellow Dept. of Statistics The University of
HT> Warwick Coventry CV4 7AL
HT> Tel: 024 76575870 Fax: 024 76524532 Url:
HT> www.warwick.ac.uk/go/heatherturner
HT> ______________________________________________
HT> R-devel at r-project.org mailing list
HT> https://stat.ethz.ch/mailman/listinfo/r-devel
No virus found in this incoming message.
Checked by AVG.
Version: 8.0.100 / Virus Database: 270.2.0/1494 - Release Date:
6/10/2008 7:22 AM
Dr H Turner Research Fellow Dept. of Statistics The University of Warwick Coventry CV4 7AL Tel: 024 76575870 Fax: 024 76524532 Url: www.warwick.ac.uk/go/heatherturner -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: bug.report.R URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080611/fe474b10/attachment.pl> -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: create.post_unix.R URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080611/fe474b10/attachment-0001.pl> -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: create.post_win.R URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080611/fe474b10/attachment-0002.pl> -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: help.request.R URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080611/fe474b10/attachment-0003.pl> -------------- next part -------------- An embedded and charset-unspecified text was scrubbed... Name: help.request.Rd URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20080611/fe474b10/attachment-0004.pl>
"HT" == Heather Turner <Heather.Turner at warwick.ac.uk>
on Wed, 11 Jun 2008 12:50:49 +0100 writes:
HT> Okay, here's the update.
HT> I've created a new function create.post() (with Windows and Unix
HT> versions) which would be the internal function that creates the post
HT> template ready to edit and optionally send. In the Windows version I've
HT> added an experimental method == "mailto" option, which will open the
HT> post template in the default mailer (e.g. Outlook) ready to edit and
HT> post. Maybe a Unix version would also be nice, e.g.
HT> browseURL("mailto:r-bugs at r-project.org?subject=my bug&body=%0A<<insert
HT> bug report here>>%0A%0A%0A%0A--please do not edit the information
HT> below--%0A%0AVersion:%0A platform = x86_64-unknown-linux-gnu%0A ...")
HT> would open the post template in e.g. Thunderbird, but has the side
HT> effect of opening an empty page in the web browser. I don't know if
HT> there's a neater solution?
Well, the current solution {for bug.report()} seems quite
desirable to me on unix.
HT> The create.post() function is basically the old bug.report() with two
HT> extra arguments: 'description' (e.g. "bug report") and 'instructions'
HT> (e.g. "\\n<<Type your message here>>\\n") for customization. It could be
HT> used directly e.g to post to R-devel with session information.
HT> The new bug.report() simply calls create.post() with the appropriate
HT> arguments.
Thank you; that's a really nice example of code reuse!
HT> The improved help-request() function calls create.post() after running
HT> through the checks described before.
HT> In response to Gabor's comments, help.request():
HT> - now checks packages are up-to-date and gives option to update
HT> on-the-fly (user may not know whether involved in query, so check all)
This is a bit problematic as now.
E.g., we have about 1500 packages installed, and inspite of automatic
updating, never all are current, and the updating should typically
not happen on a user (but a site-wide) level anyway.
Also, the call to old.packages() takes minutes (the
first time in an R session) if you have so many packages in a
dozen libraries.
This should really not interfere with an e-mail for help,
rather I think that the "packages-up-to-date check"
should only happen for those non-standard packages that are
currently in use as from sessionInfo().
Unfortunately, that functionality to do that is not yet there
in old.packages(), but I am about to add that option to R-devel
as well.
No need to send me a new version of your code, BTW, since I have
already worked on it in several places.
HT> - keeps default mailing options as in old bug.report() but
HT> create.post() gives clearer message ("Email the post now?\n (yes/no)")
HT> requiring definite response ("yes" vs "y")
ok.
HT> - still uses online documents because some are only available online
HT> (R Site Search, posting guide), it ensures the most up-to-date
HT> documentation is used, and it allows direction to global FAQ page,
HT> avoiding need to check whether user is on Windows/Mac
HT> - uses more robust method of checking R version is up-to-date
HT> I've also written a help file for help.request() which includes the
HT> method="mailto" option.
ok {it did need some correction}.
HT> The help file for bug.report would need updating
HT> if this option was kept.
I think this is mainly a windows feature (but maybe not).
I'd definitely like to get some feedback from Windows users
about this.
HT> Best wishes,
HT> Heather
Thanks again, Heather, for this.
This is becoming a very nice new feature!
Martin