[Rd] No RTFM?

[Paul Johnson]

On Sun, Aug 22, 2010 at 9:22 PM, Ted Harding
<Ted.Harding at manchester.ac.uk> wrote:
>
> (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