[R-wiki] Top level organization

[Philippe Grosjean]

Gabor Grothendieck wrote:
> On 2/3/06, Ben Bolker <bolker at zoo.ufl.edu> wrote:
> 
>>Gabor Grothendieck wrote:
>>
>>>This is looking very good.
>>
>>  definitely agree.  I think we may eventually want
>>to tweak the categories in Tips&tricks, but we're getting
>>to the point now where we'll need to let some material
>>accumulate before we can really decide on the best
>>arrangement.
>>
>>A few comments:
>>
>>>- what is the difference among Manuals, Cookbooks and Tips and Tricks.
>>>Its not clear to me.
>>
>>   Manuals and "cookbooks" are longer and by a single or a few authors;
>>tips and tricks are shorter and more collaborative (I've tried to
>>clarify a little bit by adding a few short descriptions to
>>"start2").  That said, I think the subdivision within "Guides"
> 
> 
> This is still not clear..  There are THREE categories currently,
> not two.  The three possible categories I can see are:
> 
> - official R manuals.  The official manuals that come with R wifieid.

No, there is no plan to wikify the official R manuals (just a link to 
their PDF version on CRAN). There will be only a wikified version of the 
online help on R functions (in the R documentation section). This serves 
two purposes:

1) Provide context-sensitive help on R function inside the Wiki and

2) Allow to add comment at the end, using a discussion plugin.

> - other R documents.  Contributions from users.

Yes. For large documents, it goes to 'Guides', and for small pages, to 
'Tips & Tricks'

> - snippets.  Paul Johnson's collection, etc.

Now 'Tips & Tricks' (because someone argue that 'snippets' is not veryh 
easy to understand, and I agree -as a non-English, I had to consult a 
dicitionnary!-)

> Is that the distinction?  Should it be?

Yes!
- R Documentation will use an automated script to be updated regularly 
from the latest .Rd files. for that technical reason, it must be in a 
separate section
- Large documents and small ones are managed in a radically different 
way: large are mainly edited by one, or a few authors that are 
responsible of their structure (within the document). So, few 
subsections -- structure *within* the documents. Small items are really 
a collaborative work, and we need a separate section with a much larger 
number of subsections if we hope to keep a little bit of an organization 
with these short pages -- structure *in the subsections*, *on top* of 
each little document. For that reason, we cannot mix large and small 
docs on the server's harddisk and hope to get a good compromize in the 
sections/subsections definition.

*** Please, recall that the structure we define is the organization of 
pages on the server's harddisk! *** If needed, we can design tables of 
content that mix items from R doc, Guides and Tips & Tricks in a free 
way (for instance, to write a TOC that collects together all material 
related to data frame manipulation, or to scatterplots, or to GAM, or ...)

Best,

Philippe Grosjean

>>(which is a fine category heading) could use a little polishing/
>>explanation. [e.g. I might add a "Field-specific" category]
>>Phillippe, perhaps (in your copious spare time :-) ) you could
>>give slightly longer descriptions of how you envision the sections
>>within "Guides" and we could work from there?
>>
>>
>>>- Translations sounds like different spoken languages such as French,
>>>German, etc.  Maybe this could read something like this: Guides
>>>to R for users of Matlab, Octave, Stata and other packages.
>>
>>  you'll see this is now changed.
>>  (is there a single source anywhere for non-English-language
>>R resources? there is a section in other-docs.html on R-project;
>>a few non-English books in doc/bib/R-books.html; a fairly hefty
>>set of contributed non-English docs in other-docs.html on CRAN
>>(!! different from other-docs.html on R-project !!); translation
>>information at developer.r-project.org/Translation.html and ...
>>TranslationTeams.html; some info in the R Installation and
>>Administration manual ...)  Perhaps there should be *another*
>>Translation page under "Getting started" ... ????
>>
>>  cheers
>>    Ben
>>
>>
>>--
>>620B Bartram Hall                            bolker at zoo.ufl.edu
>>Zoology Department, University of Florida    http://www.zoo.ufl.edu/bolker
>>Box 118525                                   (ph)  352-392-5697
>>Gainesville, FL 32611-8525                   (fax) 352-392-3704
>>
> 
> 
>