R's documentation

On Fri, May 29, 2009 at 05:20:24PM +0100, Patrick Burns wrote:

If you find some documentation that is
confusing, then you can write a message
about it that states:

I think that some kind of a glossary would be helpful.  Then I would know
whether certain words or phrases are R-specific or whether they come from
statistics, so I'd at least know where should I continue to dig further.

A text explaining how data frames *are meant to be used* would be helpful.
The intro to data frames is clear (collection of vectors of same length),
but it left me clueless about how functions interpret the data inside.  It
finally clicked for me when I was reading some intro about lattice graphics
and where I actually had to display the builtin data-set.  Such a basic
concept should be explained somewhere without the user needing to basically
reverse-engineer the concept.  In other words, the "Introduction to R"
should contain something about "long" and "wide" data formats.  Or at least
links to proper descriptions should be given (plyr, reshape packages).

Implicit conversions are vague.  If variable x is a factor, what does
x==8 do?   Convert 8 to string and compare to one of the levels of x?
Compare as.numeric(x) with 8?  Simple experiment reveals this, but
help("==") does not shed light on the issue. (".. or other objects
for which methods have been written.")  This raises a bunch of questions:
What kind of objects are there in R?  How do I find object's methods?
How do I find overload of == that compares factors and integers (or at
least HELP for a particular overload)?  The help on "==" is precise, but
utterly useless for somebody who does not already know 1) what == does,
and 2) all the other wider concepts mentioned in the help text.

[And so on.. this was just the example that was lately bothering me.  In
general, more cross-referencing between documentation topics might be helpful.
"SEE ALSO" is not sufficient; hyperlinking would be much more effective because
it hints at whether a topic is documented or not.]

I'm an experienced developer, yet it took me three months to go over from
5-dimensional arrays and fudging with apply() margins to "proper" use of
data-frames.  Had I needed somewhat simpler data manipulation or graphics, I
would have thrown out R out of the window, as I have many times before.   
Things *should not* be that way.  For an example of what I consider to be
well-structured documentation, please see

http://doc.qtsoftware.com/4.5/how-to-learn-qt.html

which made it possible for me to figure out reasonably quickly how to do what I
needed without the need for internet searches or asking on mailing lists.

[And so on, and so on.. I can only describe the help text as "opaque".  Reading
it feels like reading a foreign language that I'm not very proficient in.]