I believe in the great value of a Wiki for documentation purposes. Perhaps one could imagine more discussions on this mailing list being turned into a wiki entry? I would rather like that personally: the information, references, and possible solutions to a problem could all be summarized in one page, with working examples, links and graphics. This format would have some benefits over the mailing list archives (no attachments, several pages, off-topic remarks,...), and would still allow for multiple users contributions. This may provide the right trade-off between structure and content for an additional help resource.
Best regards, baptiste On 25 Apr 2008, at 15:53, Tubin wrote: > > > > 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@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. _____________________________ Baptiste Auguié Physics Department University of Exeter Stocker Road, Exeter, Devon, EX4 4QL, UK Phone: +44 1392 264187 http://newton.ex.ac.uk/research/emag http://projects.ex.ac.uk/atto ______________________________________________ R-help@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.
