[R] Documentation General Comments

[Martin Maechler]

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  ???

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.
    >>>