Re: [R] Documentation General Comments

From: baptiste Auguié <ba208_at_exeter.ac.uk>
Date: Sun, 27 Apr 2008 14:55:57 +0100

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_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.


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_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 Sun 27 Apr 2008 - 14:02:10 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 - 15:00:34 GMT.

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

list of date sections of archive