[R] Documentation General Comments

Tue Apr 22 10:25:39 CEST 2008

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