[R] Documentation General Comments
Duncan Murdoch
murdoch at stats.uwo.ca
Thu Apr 24 18:37:36 CEST 2008
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.
More information about the R-help
mailing list