No RTFM?

On Sun, Aug 22, 2010 at 9:22 PM, Ted Harding

(with Cc: to r-devel)
? ?I presume you mean "sessionInfo()". "systemInfo()" hasn't been
? ?mentioned so far, I think.

brain fart. I'm old, you know :)

. I am questioning your proposal
? ?that
? ? ?1. Every question to r-help should begin with the following.
? ? ?A. Output from the command sessionInfo()
? ? ?B. Output from Sys.getlocale()
? ? ?[etc.]
? ?Not *every* question, as I've said before. It depends on the case.

I promise this is my last post in this thread.

How about this.  I aim for more concise, direct instruction.

Hence I replace

"This guide is intended to help you get the most out of the R mailing
lists, and to avoid embarrassment. Like many responses posted on the
list, it is written in a concise manner. This is not intended to be
unfriendly - it is more a consequence of allocating the limited
available time and space to technical issues rather than to social
niceties.

The list: Remember that R is free software, constructed and maintained
by volunteers. They have various reasons for contributing software and
participating on the mailing lists, but often have limited time."

with

"People are busy, so ask your question in a useful way."

I think we need to get the most vital instructions up to the top of
the guide. And the single most vital thing is sessionInfo(), as far as
I can tell. I wish sessionInfo would just grab the locale information.

You interpret my plan as harsh/restrictive, and I don't mean it that
way.  I'm aiming for clear and understandable to tired/frustrated
people.

Suppose it is phrased it this way instead:

1. Unless you are confident that the problem you are asking about is
not affected by your OS or version of R, please include this
information with your post:

A. Output from the command sessionInfo()

B. Output from Sys.getlocale()
...


I think your experience with the befuddled users must be different
from mine. Mine are looking for a clear instruction on what to do,
they don't know what's wrong, and don't mind doing something specific
as long as they are sure you want it.

My users are perplexed by a statement like :

"Surprising behavior and bugs: What you think is a bug may be many
other things, such as a default behavior that you do not like, a
feature, an undocumented feature, or a bug in the documentation. You
do not need to commit yourself to one of these in order to ask a
question. If it is a real bug, someone will notice it. Before you post
a real bug report, make sure you read R Bugs in the R-faq. If you're
not completely and utterly sure something is a bug, post a question to
r-help, not a bug report to r-bugs - every bug report requires manual
action by one of the R-core members. Also, see Simon Tatham's essay on
How to Report Bugs Effectively.

For questions about unexpected behavior or a possible bug, you should,
at a minimum, copy and paste the output from sessionInfo() into your
message."

I don't think they get much out of this. They need to know that that
"bug" is a "fighting word" (US legal term: expression for which you
can reasonably expect to be punched in the nose, so it is not
protected free speech) for programmers and they are deeply insulted by
it, and users should never use it.  The only person who should call
something a bug is the author.  Only the Mother can say a baby is
ugly.

[3] I have tried to argue for a moderate and flexible spirit in
? ?what is advised in the Posting Guide.

I agree, but can it be done more clearly and concisely.

pj

Paul E. Johnson
Professor, Political Science
1541 Lilac Lane, Room 504
University of Kansas

I can tell. I wish sessionInfo would just grab the locale information.

Here it does so by default: locale info is included in sessionInfo
output. Regards
Liviu

sessionInfo()

R version 2.10.1 (2009-12-14)
x86_64-pc-linux-gnu

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
 [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
 [5] LC_MONETARY=C              LC_MESSAGES=en_US.UTF-8
 [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
 [9] LC_ADDRESS=C               LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base

other attached packages:
[1] fortunes_1.3-7 IPSUR_1.0

Sys.getlocale()

[1] "LC_CTYPE=en_US.UTF-8;LC_NUMERIC=C;LC_TIME=en_US.UTF-8;LC_COLLATE=en_US.UTF-8;LC_MONETARY=C;LC_MESSAGES=en_US.UTF-8;LC_PAPER=en_US.UTF-8;LC_NAME=C;LC_ADDRESS=C;LC_TELEPHONE=C;LC_MEASUREMENT=en_US.UTF-8;LC_IDENTIFICATION=C"

<snip />

[3] I have tried to argue for a moderate and flexible spirit in
    what is advised in the Posting Guide. I am very uncomfortable
    about proposals as prescriptive and rigid as yours seem to be.
    Users, especially beginners, are likely to be discouraged from
    posting to R-help if faced with stringent (and possibly not
    relevant) requirements on how they should post. If faced with
    responses which chastise them for not "following the rules"
    they may well be put off using R altogether.

    As I have said before, I see the function of R-help as helping,
    in as cooperative a way as possible. The function of the Posting
    Guide should likewise be to help them to write good questions,
    with advice on what mey be necessary, what useful, what not useful.

    The current Posting Guide is already quite reasonable in these
    respects, and perhaps would benefit most from being made being
    somewhat re-formatted, without essential change.

Ted.

I concur with Ted's comments above. Bugzilla has this form of
hand-holding, prescriptive format for filing bugs against software
projects. It works there where people are only supplying bug reports. I
don't see that it can work for the more free-form nature of a mailing
list.

The posting guide should be there to help people i) help themselves find
the information about R that they need, and if this hasn't helped ii)
formulate an appropriate question with the *relevant* information.
Earlier ideas in this thread suggested including a lot of extraneous
information not relevant to most R-Help questions.

I see Paul that in your reply that your aim is to make things more clear
and more concise. Perhaps the best way forward now, if you are
sufficiently motivated and have the time, would be to rewrite the
posting guide and send it to the list for comments/suggestions. IIRC
this was how the original guide was produced.

G

%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%

It seems as if the original point has been buried a bit here. So I'd just like to briefly agree with what Ted Harding said about guidelines, and then return to RTFM etc.

The price paid for writing the best bit of software in the world, is that people want to use it. Some of those people will be clueless. For some, cluelessness is temporary state which they will crawl or be helped out of; for others, sadly, not. It's impossible to tell from a single email whether someone is part of "the deserving poor" or just "an idle bludger", so replies shouldn't assume the latter. Quite a bit of R doco is still at best machine-readable (despite creeping improvements, for which thank you somebody) and assumes a lot of prior knowledge, so it's hardly surprising there are dumb questions. If anyone's going to take the time to reply, they might as well do so properly. I appreciate the community spirit of those who help on R-help (which I don't manage to do), and I do have sympathy with the desire to keep down traffic, and yes sometimes RTFM is the right answer, but the current false-negative rate strikes me as too high. In that spirit:

 - How about a 24-hour "no RTFM" rule? That gives more sympathetic respondents the chance to come up with something a bit more helpful. After that, if there's no response, then anyone who still cares to can pounce on the victim-- who will by then have had 24 hours of ominous silence in which to try to find the right FM to R, as someone else nicely put it.

 - Also, "?glm" does come over as pretty rude, possibly worse than RTFM which at least has the ghost of humour. Even when it's the right answer, personally I would never say it without a prefacing "Have a look at ..." or somesuch-- about 2 seconds' worth of typing to avoid crushing some tender soul & coming across as an obnoxious Neanderthal. In any case, it usually requires a more specific reference in order to be useful. Some R documentation is long-- and in many cases should actually be longer, I think-- so it is not always easy to find the relevant bits. A good template might be something like this:

"Have a look at ?glm and search for 'fitted probabilities' "

No 24 hour rule seems necessary for specific refs to documentation if a formula like that is followed, I reckon-- just for RTFM.

bye
Mark

Mark Bravington
CSIRO Mathematical & Information Sciences
Marine Laboratory
Castray Esplanade
Hobart 7001
TAS

On Mon, 2010-08-23 at 03:22 +0100, Ted.Harding at manchester.ac.uk wrote:
<snip />
>
> [3] I have tried to argue for a moderate and flexible spirit in
>     what is advised in the Posting Guide. I am very uncomfortable
>     about proposals as prescriptive and rigid as yours seem to be.
>     Users, especially beginners, are likely to be discouraged from
>     posting to R-help if faced with stringent (and possibly not
>     relevant) requirements on how they should post. If faced with
>     responses which chastise them for not "following the rules"
>     they may well be put off using R altogether.
>
>     As I have said before, I see the function of R-help as helping,
>     in as cooperative a way as possible. The function of the Posting
>     Guide should likewise be to help them to write good questions,
>     with advice on what mey be necessary, what useful, what not useful.
>
>     The current Posting Guide is already quite reasonable in these
>     respects, and perhaps would benefit most from being made being
>     somewhat re-formatted, without essential change.
>
> Ted.

I concur with Ted's comments above. Bugzilla has this form of
hand-holding, prescriptive format for filing bugs against software
projects. It works there where people are only supplying bug reports. I
don't see that it can work for the more free-form nature of a mailing
list.

The posting guide should be there to help people i) help themselves find
the information about R that they need, and if this hasn't helped ii)
formulate an appropriate question with the *relevant* information.
Earlier ideas in this thread suggested including a lot of extraneous
information not relevant to most R-Help questions.

I see Paul that in your reply that your aim is to make things more clear
and more concise. Perhaps the best way forward now, if you are
sufficiently motivated and have the time, would be to rewrite the
posting guide and send it to the list for comments/suggestions. IIRC
this was how the original guide was produced.

G

--
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%
 Dr. Gavin Simpson             [t] +44 (0)20 7679 0522
 ECRC, UCL Geography,          [f] +44 (0)20 7679 0565
 Pearson Building,             [e] gavin.simpsonATNOSPAMucl.ac.uk
 Gower Street, London          [w] http://www.ucl.ac.uk/~ucfagls/
 UK. WC1E 6BT.                 [w] http://www.freshwaters.org.uk
%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%~%

______________________________________________
R-devel at r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

?- Also, "?glm" does come over as pretty rude,

Personally I've always seen the '?fun' answers as appropriate and
straight to the point. There's no need to type a nice sounding phrase
? la fran?aise just to express 'see the ?glm reference'. A
'requirement' for long phrases might deter some in a hurry to answer
at all, and in my view a quick and raw reference is better than none.

Perhaps a first time poster would be utterly clueless on first sight,
but doing a bit of homework with the key word in hands one should
quickly understand what's all about. The second sight of '?fun'
answers shouldn't be that intimidating.

Regards
Liviu