Re: [R] Documentation General Comments

From: Tubin <sredmonson_at_yahoo.com>
Date: Fri, 25 Apr 2008 07:53:49 -0700 (PDT)

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.

______________________________________________
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.
Received on Fri 25 Apr 2008 - 15:22:58 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Sun 27 Apr 2008 - 14:30:31 GMT.

Mailing list information is available at HREF="https://stat.ethz.ch/mailman/listinfo/r-help">https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.

list of date sections of archive