[R] Documentation General Comments

[Duncan Murdoch]

On 4/24/2008 10:22 AM, Beck, Kenneth (STP) wrote:
> Agree that terseness is good, but I also agree with other posters that
> better cross referencing or maybe an index of synonyms would be good. 
> 
> So far, the best suggestion is the pdf at this link 
> 
> (http://www.medepi.net/epir/epir_chap02.pdf). 
> 
> Is there a way to pop at least part of this into the R-base help page?

That's an easy question to answer:  no.  There is no way to just pop it 
in.  Incorporating it would take a lot of thought and work.

> Are there legal or copyright issues?

That's also easy:  yes, there are.  The authors of that chapter 
presumably have copyright in it (unless they've transferred it to 
someone else).  Without their permission it would be illegal to pop it 
into R.

  If I had known this from the start,
> it would have been much better. A good analogy is that old cartoon of
> the blind guys trying to figure out what an elephant is. The guys
> feeling at the front get a much different impression than the guys
> poking at the back side. I felt like that using R data structures,  had
> to blindly poke around trying different things, 90% of which did not
> work, yeilding only error messages, but now knowing the underlying
> organisation it is going much more smoothly. Ideally this kind of basic
> info would be in the core R docuemtation, you should not have to search
> this hard to get it!

All of the (correct) information in that chapter is in the core 
documentation.  They make a number of simplifications, which I think are 
appropriate for their audience, but you shouldn't believe everything you 
read there.  The core documentation has to aim for a different target, 
because it needs to be correct.

Duncan Murdoch

> 
> -----Original Message-----
> From: r-help-bounces at r-project.org [mailto:r-help-bounces at r-project.org]
> On Behalf Of Bert Gunter
> Sent: Tuesday, April 22, 2008 10:29 AM
> To: r-help at r-project.org
> Subject: Re: [R] Documentation General Comments
> 
> FWIW:
> 
> I consider the documentation of Core R to be one of its great strengths:
> it is terse (read: to the point), detailed, and accurate. I find it
> eminently useful and helpful. Indeed, it was why I made the decision
> some years ago to switch from S-Plus to R (I readily acknowledge that
> S-Plus may have improved its docs since then -- haven't looked at it in
> years). While I understand that it may not suit everyone -- learning
> styles differ, after all -- may I at least say that there is one user
> out here who is appreciative of the hard work and care that has gone
> into the documentation. Far FAR better than anything I could do!
> 
> -- Bert Gunter
> Genentech
> 
> -----Original Message-----
> From: r-help-bounces at r-project.org [mailto:r-help-bounces at r-project.org]
> On Behalf Of Greg Snow
> Sent: Tuesday, April 22, 2008 8:16 AM
> To: Beck, Kenneth (STP); r-help at r-project.org
> Subject: Re: [R] Documentation General Comments
> 
> This is a case of you can't please everyone.  A while back there was
> some complaint that "Introduction to R" spent to much time on talking
> about the different types of variables, just the opposite complaint of
> yours.
> 
> There are several other sources of documentation (look under the books
> link on the R homepage or the contributed documentation link on any CRAN
> site, also browse through the newsletter).  For more in depth
> information on variable types and object oriented programming in R you
> may want to invest in a copy of "S Programming" by Venables and Ripley.
> 
> If you have specific questions (about data types, or other) then tell us
> what you have read and what you still do not understand and you are more
> likely to get a useful answer.  (also read the posting guide that is
> referenced at the bottom of almost all posts to the list).
> 
> --
> Gregory (Greg) L. Snow Ph.D.
> Statistical Data Center
> Intermountain Healthcare
> greg.snow at imail.org
> (801) 408-8111
>  
>  
> 
>> -----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 3: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.
>> 
> 
> ______________________________________________
> 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.
> 
> ______________________________________________
> 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.
> 
> ______________________________________________
> 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.