Re: [R] Documentation General Comments

From: Beck, Kenneth (STP) <Kenneth.Beck_at_bsci.com>
Date: Tue, 22 Apr 2008 08:06:41 -0500

Well, I don't think I will live for the rest of my days in a pub, but thanks to all so far for comments. I actually am willing to help, though not sure in what capacity.

-----Original Message-----
From: Rolf Turner [mailto:r.turner_at_auckland.ac.nz] Sent: Monday, April 21, 2008 7:03 PM
To: r-help
Cc: Beck, Kenneth (STP); Dr. Jeff Miller Subject: Re: [R] Documentation General Comments

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 confidential. If you are not the intended recipient please delete the message and notify the sender. Any views or opinions presented are solely those of the author.

This e-mail has been scanned and cleared by MailMarshal www.marshalsoftware.com

######################################################################

______________________________________________
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 - 13:15:29 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 - 13:30:32 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