[R] Documentation General Comments

Beck, Kenneth (STP) Kenneth.Beck at bsci.com
Mon Apr 28 18:57:44 CEST 2008


Thanks, the reference to the wiki and ways to submit patches is a help. 

-----Original Message-----
From: Kingsford Jones [mailto:kingsfordjones at gmail.com] 
Sent: Thursday, April 24, 2008 10:56 PM
To: Duncan Murdoch
Cc: Martin Maechler; r-help at r-project.org; Beck, Kenneth (STP); Bert
Gunter
Subject: Re: [R] Documentation General Comments

I just read through this thread and I didn't see the R Language
Definition mentioned.  As with An Introduction to R it can be accessed
-- at least in my Windows GUI -- via the menu bar: Help -> Manuals (in
PDF).  If An Introduction to R is too basic, then the Language
Definition should be a good place to look for more details on R objects
(Ch 2).  However An Introduction to R does include authoritative
introductions to the "data types" mentioned by the original poster:
factors (Ch4), arrays and matrices (Ch 5), and lists and data frames (Ch
6).

That said, I agree that learning efficiency could be improved by
augmenting the manuals with tables similar to the table 2.1 that was
referenced earlier in the thread (aside: are functions, or even lists,
really "Data Objects"?). Of course, as pointed out by Duncan, we are
collaborators not consumers, so if I think there should be more tables
in the documents then the onus is on me to try to get my ideas
incorporated (see
http://wiki.r-project.org/rwiki/doku.php?id=misc:rpatch ).

Kingsford Jones

On Thu, Apr 24, 2008 at 9:37 AM, Duncan Murdoch <murdoch at stats.uwo.ca>
wrote:
> On 4/24/2008 12:08 PM, Martin Maechler wrote:
>  > Hmm,
>  >
>  >>>>>> "KeBe" == Beck, Kenneth (STP) <Kenneth.Beck at bsci.com>
>  >>>>>>     on Thu, 24 Apr 2008 10:12:19 -0500 writes:
>  >
>  >     KeBe> OK I've spent a lot of time with the core
>  >     KeBe> documentation, and I never found anything as simple as
>  >     KeBe> their table 2.1, which elucidated the difference
>  >     KeBe> between a vector, matrix and array first, then the
>  >     KeBe> higher level structures, frame and list.  Maybe I'm
>  >     KeBe> not a good searcher, but believe me for every initial
>  >     KeBe> posting I submit to this group, I have spent hours
>  >     KeBe> trying to find the answer elsewhere. And, as you
>  >     KeBe> state, maybe I am now deluded by that presentation,
>  >     KeBe> maybe it is not this simple!
>  >
>  > Well, I get the impression that you've never read the manual
>  >       "Introduction to R"
>  >       (or some good book such as Peter Dalgaard's)
>  > but have directly jumped into reading  help() pages  ???
>
>  That's not correct.  Kenneth started the thread (on Monday) saying:
>
>
>  "The basic tutorial "Introduction to R" is so basic, it  hardly helps

> at all, then digging through documentation is really an  exercise in 
> frustration."
>
>  Duncan Murdoch
>
>
>
>  >
>  > Maybe a good idea would be to improve the "Introduction to R"
>  > rather than thinking of misusing the help() collection  > {which is

> the "reference manual", not the "user manual" !!}  > by making it easy

> to understand (and consequently less precise) ??
>  >
>  > Patches (well reflected ..) to the "Introduction" are quite  > 
> welcome, indeed.
>  > The (development) source is always available  > at 
> https://svn.r-project.org/R/trunk/doc/manual/R-intro.texi
>  >
>  > (and yes, the source does look a bit less user-friendly,  >  than 
> its PDF output, e.g.
>  >  http://cran.r-project.org/doc/manuals/R-intro.pdf
>  >  or its >> daily updated << HTML output at  >  
> http://stat.ethz.ch/R-manual/R-devel/doc/manual/R-intro.html
>  > )
>  >
>  > Regards,
>  > Martin
>  >
>  >     KeBe> Look at the help for data.frame. VERY terse
>  >     KeBe> explanation, with not a good comparison to the other
>  >     KeBe> data types. Then, look at the titles list. Where is a
>  >     KeBe> topic for "data types" Every other programming
>  >     KeBe> language I have used (C++, Pascal, SAS, Java) has a
>  >     KeBe> basic chapter in the documentation that goes over data
>  >     KeBe> types, what arrays are, higher level structures, etc.
>  >     KeBe> When I typed help.search("data type") I get the
>  >     KeBe> following:
>  >
>  >     KeBe> Help files with alias or concept or title matching
>  >     KeBe> 'data type' using fuzzy matching:
>  >     KeBe> character-class(methods) Classes Corresponding to
>  >     KeBe> Basic Data Types sqlTypeInfo(RODBC) Request
>  >     KeBe> Information about DataTypes in an ODBC Database
>  >
>  >     KeBe> Looking for the term "character-class(methods)" yields
>  >     KeBe> nothing. I don't think that is what I want!
>  >
>  >     KeBe> Given all this complaining, I actually have completed
>  >     KeBe> several nice project using "R", it is an impressive
>  >     KeBe> package. Somehow, though, we need to make the
>  >     KeBe> documentation better.
>  >
>  >     KeBe> -----Original Message----- From: Duncan Murdoch
>  >     KeBe> [mailto:murdoch at stats.uwo.ca] Sent: Thursday, April
>  >     KeBe> 24, 2008 9:51 AM To: Beck, Kenneth (STP) Cc: Bert
>  >     KeBe> Gunter; r-help at r-project.org Subject: Re: [R]
>  >     KeBe> Documentation General Comments
>  >
>  >     KeBe> 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?
>  >
>  >     KeBe> That's an easy question to answer: no.  There is no
>  >     KeBe> way to just pop it in.  Incorporating it would take a
>  >     KeBe> lot of thought and work.
>  >
>  >     >> Are there legal or copyright issues?
>  >
>  >     KeBe> That's also easy: yes, there are.  The authors of that
>  >     KeBe> chapter presumably have copyright in it (unless
>  >     KeBe> they've transferred it to someone else).  Without
>  >     KeBe> their permission it would be illegal to pop it into R.
>  >
>  >     KeBe>   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!
>  >
>  >     KeBe> All of the (correct) information in that chapter is in
>  >     KeBe> the core documentation.  They make a number of
>  >     KeBe> simplifications, which I think are appropriate for
>  >     KeBe> their audience, but you shouldn't believe everything
>  >     KeBe> you read there.  The core documentation has to aim for
>  >     KeBe> a different target, because it needs to be correct.
>  >
>  >     KeBe> 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
>  >     KeBe> 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
>  >     KeBe> 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
>  >     KeBe> 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.
>



More information about the R-help mailing list