[R] Documentation General Comments

[Beck, Kenneth (STP)]

OK I've spent a lot of time with the core documentation, and I never
found anything as simple as their table 2.1, which elucidated the
difference between a vector, matrix and array first, then the higher
level structures, frame and list.  Maybe I'm not a good searcher, but
believe me for every initial posting I submit to this group, I have
spent hours trying to find the answer elsewhere. And, as you state,
maybe I am now deluded by that presentation, maybe it is not this
simple!

Look at the help for data.frame. VERY terse explanation, with not a good
comparison to the other data types. Then, look at the titles list. Where
is a topic for "data types" Every other programming language I have used
(C++, Pascal, SAS, Java) has a basic chapter in the documentation that
goes over data types, what arrays are, higher level structures, etc.
When I typed help.search("data type") I get the following:

Help files with alias or concept or title matching 'data type' using
fuzzy matching:
character-class(methods)
                        Classes Corresponding to Basic Data Types
sqlTypeInfo(RODBC)      Request Information about DataTypes in an ODBC
                        Database

Looking for the term "character-class(methods)" yields nothing. I don't
think that is what I want!

Given all this complaining, I actually have completed several nice
project using "R", it is an impressive package. Somehow, though, we need
to make the documentation better.

-----Original Message-----
From: Duncan Murdoch [mailto:murdoch at stats.uwo.ca] 
Sent: Thursday, April 24, 2008 9:51 AM
To: Beck, Kenneth (STP)
Cc: Bert Gunter; r-help at r-project.org
Subject: Re: [R] Documentation General Comments

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.