[R] Documentation General Comments
ba208 at exeter.ac.uk
Sun Apr 27 15:55:57 CEST 2008
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
This may provide the right trade-off between structure and content
for an additional help resource.
On 25 Apr 2008, at 15:53, Tubin wrote:
> I realize the R developers are probably overwhelmed and have little
> for this, but the documentation really needs some serious
> My reply:
> I'm quite new to R and so have spent a lot of time in the last few
> 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.
> people have posted about potential projects in several threads - so
> I'll try
> combining those thoughts in a new response thread.
> 1) New users have questions based on common tasks, which don't
> reflect the structure of the language
> 2) There's a lot of good documentation out there already, both
> official and
> 3) It doesn't break intellectual property laws to create an
> bibliography" of existing references, with a task-based topic
> 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
> Detailed comments:
> One thing I notice in the official documentation is that it's
> around the R language structure. The "help" table of contents does
> a listing of natural-language titles, but they're listed
> rather than organized by task-based concept.
> But when you look at the forums, the new users are searching for
> by task or by concept - what are the classes of object? How do I
> 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
> 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
> expressions" or "manipulating data in dataframes" - and often a
> 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
> 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-
> Sent from the R help mailing list archive at Nabble.com.
> R-help at r-project.org mailing list
> PLEASE do read the posting guide http://www.R-project.org/posting-
> and provide commented, minimal, self-contained, reproducible code.
University of Exeter
EX4 4QL, UK
Phone: +44 1392 264187
More information about the R-help