[R] Documentation General Comments

[baptiste Auguié]

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