From Mark.Bravington at csiro.au  Tue Aug 24 04:17:10 2010
From: Mark.Bravington at csiro.au (Mark.Bravington at csiro.au)
Date: Tue, 24 Aug 2010 12:17:10 +1000
Subject: [Rd] No RTFM?
In-Reply-To: <1282552663.2375.26.camel@desktop.localdomain>
References: <XFMail.100823032204.Ted.Harding@manchester.ac.uk>,
	<1282552663.2375.26.camel@desktop.localdomain>
Message-ID: <62C82B39B8A85E4B95A18F7F7B852F870576DBBB72@exvic-mbx03.nexus.csiro.au>

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

________________________________________
From: r-devel-bounces at r-project.org [r-devel-bounces at r-project.org] On Behalf Of Gavin Simpson [gavin.simpson at ucl.ac.uk]
Sent: 23 August 2010 18:37
To: ted.harding at manchester.ac.uk
Cc: r-devel at r-project.org
Subject: Re: [Rd] No RTFM?

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



[Rd] No RTFM?
Mark.Bravington at csiro.au