Re: [R] Documentation General Comments

From: baptiste Auguié <ba208_at_exeter.ac.uk>
Date: Tue, 22 Apr 2008 09:25:39 +0100

After a few months now of climbing the R learning curve (thanks to the list, btw), I've now entered the stage where I sometimes get to hold the torch and safety rope for newcomers around me. Writing your own package makes you very aware of the issues discussed in this thread.

However, I see a compromise that has not been discussed: the use of a Wiki. There is at least one dedicated R wiki, and I think this is a wonderful opportunity to encourage collaborative documentation that is helpful to everyone. If a new user is not happy with the doc for whatever function, he starts an entry with his problem, and others will reshape the page to come up with clearer and specific explanations.

cheers,

baptiste

On 22 Apr 2008, at 01:03, Rolf Turner wrote:

>
> The root of the problem is that R is a voluntary/cooperative project
> and those
> who develop and maintain R are (generously) contributing their time
> and
> probably have little-to-no time left over to devote to the
> improvement of the
> documentation.
>
> The generic answer to such a dilemma is that those who see
> deficiencies in
> R or in its documentation should volunteer to remedy or contribute to
> the
> remediation of those deficiencies. But there is a problem.
>
> Those of us who see deficiencies often (usually?) simply don't
> ***know***
> enough to undertake the remediation. This is particularly true in
> respect
> of inadequacies of documentation. If we knew enough to improve the
> documentation
> we probably wouldn't have been motivated to whinge about the
> deficiency
> in the first place.
>
> An ``obvious'' solution to this dilemma is that us bunnies should
> privately
> seek tutelage from gurus who do know enough and then when we have
> properly
> understood the issues, pass on our learning by re-writing the
> documentation.
> This is a good theory, but doesn't really work in practice. The
> gurus are
> usually too busy to provide tutelage --- it would probably be less
> time consuming
> for them to write the documentation themselves. More problematic
> still is
> that if you ask a guru for more explanation the guru will, more often
> than
> not, get very grumpy and tell you to stop wasting their time. After
> all, the
> situation is very clear to *them*. They understand the existing
> documentation
> perfectly --- why don't you?
>
> This is why the documentation tends to be opaque in the first place.
> The
> people who build R are so clever and understand so much that they
> cannot
> put themselves in the shoes of those of us who are not so blessed with
> intelligence and erudition. So they (often) write terse cryptic
> instructions
> which (often) depend on background knowledge that many of us lack.
> That
> background knowledge can of course be found ***if you know where to
> look***
> --- or even if you don't, given that you are prepared to put in
> sufficient
> time and effort searching ***and*** are clever at searching. It's
> that
> last requirement that leaves *me* out in the cold.
>
> So what's the solution? Short answer --- there probably isn't one.
> My take
> on it is ``Give up and go to the pub!'' :-)
>
> Rolf Turner
>
>
> On 22/04/2008, at 10:36 AM, Dr. Jeff Miller wrote:
>
>> I agree completely. Maybe it's time for an exhaustive manual (with
>> weekly
>> downloadable updates, of course).
>>
>> It would also be nice if it were cross-referenced. For example, to
>> get what
>> I wanted last weekend from a simple 2x2 contingency analysis, I
>> had to
>> bounce between 4 different libraries. (All I was trying to do was
>> replicate
>> the output from SAS Proc Freq).
>>
>> A lot of the library documentations have a See Also section but
>> these may be
>> getting out of date.
>>
>> But maybe our request is too monumental to be feasible. (?)
>>
>> Jeff
>>
>>
>>
>> -----Original Message-----
>> From: r-help-bounces_at_r-project.org [mailto:r-help-bounces_at_r-
>> project.org] On
>> Behalf Of Beck, Kenneth (STP)
>> Sent: Monday, April 21, 2008 5:56 PM
>> To: r-help_at_r-project.org
>> Subject: [R] Documentation General Comments
>>
>> I realize the R developers are probably overwhelmed and have little
>> time for
>> this, but the documentation really needs some serious reorganizaton.

>> A good through description of basic variable types would help a
>> lot, e.g.
>> the difference between lists, arrays, matrices and frames. And, it
>> appears
>> there is some object-orientation to R, but it is not complete. I
>> can't, for
>> instance find a "metafile" method for a "recordedplot" type, using
>> either
>> the variable direclty or the replayPlot() method. I am sorry to
>> post this,
>> but I am really having trouble sorting out certain methods in "R".
>> The basic
>> tutorial "Introduction to R" is so basic, it hardly helps at all,
>> then
>> digging through documentation is really an exercise in frustration.
>> The
>> SimpleR is also so basic it is of little help other than to just get
>> started. I occasionally find answers in the mailing list. See my
>> later post
>> on recordPlot for a good example.
>>
>> Internal Virus Database is out-of-date.
>> Checked by AVG Free Edition.
>>
>> 11:27 AM
>>
>>
>>
>> Internal Virus Database is out-of-date.
>> Checked by AVG Free Edition.
>>
>> 11:27 AM
>>
>> ______________________________________________
>> R-help_at_r-project.org mailing list
>>
https://stat.ethz.ch/mailman/listinfo/r-help
>> PLEASE do read the posting guide http://www.R-project.org/posting-
>> guide.html
>> and provide commented, minimal, self-contained, reproducible code.
>
>
> ######################################################################
> Attention:\ This e-mail message is privileged and confid...
> {{dropped:9}}
>
> ______________________________________________
> R-help_at_r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/posting-
> guide.html
> and provide commented, minimal, self-contained, reproducible code.


Baptiste Auguié

Physics Department
University of Exeter
Stocker Road,
Exeter, Devon,
EX4 4QL, UK

Phone: +44 1392 264187

http://newton.ex.ac.uk/research/emag
http://projects.ex.ac.uk/atto



R-help_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code. Received on Tue 22 Apr 2008 - 08:39:10 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Tue 22 Apr 2008 - 09:30:30 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.

list of date sections of archive