[R] Documentation General Comments

[Tubin]

I realize the R developers are probably overwhelmed and have little time
for this, but the documentation really needs some serious reorganizaton.

My reply:

I'm quite new to R and so have spent a lot of time in the last few days
reading documentation both online and text.  I'm incredibly impressed by the
language and, overall, by the documentation - the documentation tools are so
well integrated into the program, and in most cases the documentation does a
good job of balancing brevity and completeness. The original poster noted a
need for "reorganization" (not revision) and I think that's key.  Several
people have posted about potential projects in several threads - so I'll try
combining those thoughts in a new response thread.

Summary:  
1)  New users have questions based on common tasks, which don't necessarily
reflect the structure of the language
2)  There's a lot of good documentation out there already, both official and
unofficial
3)  It doesn't break intellectual property laws to create an "annotated
bibliography" of existing references, with a task-based topic structure.
4) I suspect new and old users would contribute to such a project if it
allowed external contributions - as in, suggest a resource (under an
existing topic) along with a brief explanation about why that resource was
helpful.

Detailed comments:

One thing I notice in the official documentation is that it's organized
around the R language structure.  The "help" table of contents does include
a listing of natural-language titles, but they're listed alphabetically
rather than organized by task-based concept.  

But when you look at the forums, the new users are searching for information
by task or by concept - what are the classes of object?  How do I manipulate
a data frame?  What are my tools for regular expressions?  Many of my texts
(and some independent web pages) seem to try to organize by task, but all
are incomplete - perhaps because of space limitations, perhaps because the
language is so dynamic that useful functions hadn't yet been developed when
a text was published.  Also, most of my books actually only introduce the R
language then move on to discussing the use of R for specific statistical
functions.  Yet, most of the forum questions seem to be about things like
loading and manipulating the data to get it into the appropriate format for
the desired analysis.

So I really like the suggestion to try creating some cross-indexing for the
materials that are out there already.  Perhaps a wiki-based "annotated
bibliography" with a task-based structure.  I'm tempted to suggest that we
just expand on the wikipedia content for R!  

The structure of such a thing should have categories like "managing regular
expressions" or "manipulating data in dataframes" - and often a particular
topic might be cross-referenced to more than one category, I'd think.

By annotated bibliography I mean that most of the entries under a topic
would be "here's a link or reference to a source that seems to explain this
topic well - and here's why I like it".  

And - I have to run to a meeting.  So I will stop brainstorming now.
-- 
View this message in context: http://www.nabble.com/Documentation-General-Comments-tp16821085p16895859.html
Sent from the R help mailing list archive at Nabble.com.