[R] R web site-Useability & finding varous bits of documentation

[John Kane]

--- On Thu, 6/19/08, Martin Maechler <maechler at stat.math.ethz.ch> wrote:

> From: Martin Maechler <maechler at stat.math.ethz.ch>
> Subject: Re: [R] R web site-Useability  & finding varous bits of documentation
> To: jrkrideau at yahoo.ca
> Cc: "R R-help" <r-help at stat.math.ethz.ch>
> Received: Thursday, June 19, 2008, 12:17 PM
> >>>>> "JK" == John Kane
> <jrkrideau at yahoo.ca>
> >>>>>     on Thu, 19 Jun 2008 06:50:18 -0700
> (PDT) writes:
> 
>     JK> I was starting to write a note to a prospective
> R-user
>     JK> and came to the point of explaining how to get
> useful
>     JK> introductory information on R.  After mentioning
> the
>     JK> Into and the FAQs I went on to try to explain
> how to use
>     JK> a lot of the contributed information.
> 
>     JK> However I realised that there seems to be no
> direct way
>     JK> to get to Other Publications or Contributed
>     JK> Documenation.
> 
>     JK> The best I have seen is to get to Books and then
> click
>     JK> on "other publications" which take one
> to "Publications
>     JK> related to R" or go to "other"
> (main page) and then
>     JK> click on "Contributed Documentation"
> which takes one to
>     JK> "Contributed Documentation" This seems
> less than  optimal.
> 
> that depends ...
> 
>     JK> Am I missing some more direct ways to get to
>     JK> "Publications related to R" and
> "Contributed
>     JK> Documentation"?  I remember blundering
> around the site
>     JK> for some time (days in elapsed time?) before I
> managed
>     JK> to find these documents.
> 
>     JK> If I am not we may be losing a lot of potential
> users
>     JK> who just cannot find basic documentation.  The
> Intro and
>     JK> the FAQs are invaluable 
> 
> Well, the first entry in the 'Documentation'
> section of the
> sidebar is 'Manuals' (which is considerably more
> than "The Intro
> and the FAQs"), and these are really the only
> documentation part 
> which the R core team strives to keep up-to-date.

Good point 
> 
> Every R-project page reader should realize these are the
> official docs.
> If you open it, you already get a page with a link to
> contributed docs.
> Alternatively, there's the last item of the
> 'Documentation' section of the
> sidebar, called "Other"  which does mention the
> "Contributed
> Doc.." section  >>> on CRAN <<<

Again a good point. I guess my problem is that there is no hint that the pages I was mentioning actually exist unless you go to the next page down in one or the other and then figure out which URL to click on

> 
> Note that the R-project page (www.r-project.org)  
> and  CRAN  are two "things",  albeit closely
> related.
> CRAN is for "DOWNLOAD"ing, including free
> contributed docs.
> So that is the main reason, "contrib.docs" are
> not there in the
> www.r-project.org sidebar.

I believe I understand the logic of the approach however from the point of usability it still seems a bit awkward. I am certainly not a web designer but it would seem to me that a page (if needed with a links through  CRAN) that leads to all available source of written information makes much more sense.  

As a relatively naive user still I don't see the point of providing links to external books and other external sources of information and then in those pages adding the incidental information that R and/or CRAN holds large lists of downloadable documents.

>From a newbie's point of view the main idea is to get some information on R. Speaking as a (ex)newbie, I don't care where the info comes from, from a CRAN site, from a Journal site a university site or from my local library. I first need to know that it exists and how to get it. 

The current Books and Other implies that there are two sources of information whereas there actually are four. 

Iseems to me a single page for documenation other than the official Core documentation with appropriate links makes more sense. 
All it would have is :

1. Books related to R
2. Publications related to R
3. R Documentation 
4. Contributed Documentation

I believe these 4 items cover all the non-core documention.  

I shall point out that if anyone is looking for "Publications related to R" it is referred to in the current link as "other publications". 

> 
>     JK> but not exactly the best way for a complete
> noivice to get started.
> 
> Well, I actually would want the complete novice to take
> note that
> there is much official documentation, before (s)he delves
> into one of
> the contributed docs.

I think you have a good point here but that is not actually what the current R page is doing as far as I can see. It seems to be assigning equal weights in terms of page layout to Manuals, FAQs, Newsletter, Wiki, Books, Certification, Other. 

In fact it may be that there should be more emphasis on the split between official Core documentation and the others.  Certainly as a newbie I did not even know that there was a Core group. R was R. Also more emphasis might get more newbies to read the FAQ's and the Manuals more often. 

As an aside what is the newbie's reaction to Certification? "I need to be certified to use R?"  "There's a licencing process for using R?" etc. I know the history of the topic and realise that it is an important one but it is not really an R documentation issue.  

> 
> Martin Maechler,  ETH Zurich (and part of R-core)