[R] Documentation General Comments
Lawrence Hanser
lhanser at gmail.com
Fri Apr 25 06:28:05 CEST 2008
Dear Colleagues,
It seems to me that the issue is not whether the information we seek
is in the documentation. I, for one, am amazed at the quality of the
documentation of R and of contributed materials. For me the issue is
one of finding the information in an efficient way out of the
mountains of information in the official and unofficial documentation
of R. Part of this is on the head of the seeker of information to
generate keywords that will lead a search engine to find what we are
looking for. But part of it is on the heads of contributors to insure
that relevant keywords are associated with relevant content in a way
that the search engine will find it and rank order it in a sensible
way.
Take RSiteSearch(), for example. Are we as a user and contributor
group familiar with the scoring scheme that Namazu uses to score and
order the information it finds? I refer you to:
http://www.namazu.org/doc/tips.html for this information. For
example, if Namazu finds a keyword in a <meta name ="keywords"
content="..."> tag the score is bumped by 32 points. Finding a
keyword in a <title> tag is worth 16 points, etc. Also on the
referenced url page we are essentially told not to use more than two
words in the search. It seems to me that knowing these things alone
will help authors increase the quality of searches and seekers to more
easily find what they are looking for.
My thanks to all the contributors who have made R a terrific system.
Regards,
Larry
On Thu, Apr 24, 2008 at 8:55 PM, Kingsford Jones
<kingsfordjones at gmail.com> wrote:
> 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.
> >
>
> ______________________________________________
> 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