[Rd] Wishlist: Bug reporting (PR#7349)

[dmb at mrc-dunn.cam.ac.uk]

Hello, me again. 

This is a bug regarding R website / documentation. 

On the bug site http://r-bugs.biostat.ku.dk/cgi-bin/R it would be nice to
have a description of what each bug category is, what constitutes a bug in
that category etc. You could then have the user decide which category
their bug belongs in, and save yourself a job by having to decide. Also,
knowing what each category is (and what constitutes a bug in that
category) would be generally useful.

If there is a document I should have read to answer this question, please
add a link to that document to the bugs page...
http://r-bugs.biostat.ku.dk/cgi-bin/R.


In the Bugs section of the FAQ it suggests that "If you are not sure what
the command is supposed to do after a careful reading of the manual this
indicates a bug in the manual", so I see why a slight 'could be improved'
comment is is labeled *NOT A BUG*. Not being familiar with R culture right
away this is a bit confusing, as many open source projects include this
kind of thing in the bug tracking system (even though they are not
strictly bugs). For example, suggestions on improvements to the website
can be logged in the tracker. Also I think it should be made explicit that
their is a difference between knowing what a command should do and being
able to do it.

Perhaps a line or two about how to deal with such requests in the FAQ
would be good (or on the bug site).

Personally I feel that these things are most conveniently handled by
a bug tracker. Here I think giving the user the ability to choose category
could improve the system, so people could easily ignore 'trivial' bugs,
such as bugs submitted in a new 'documentation request' category or an
'examples request' category. I firmly believe that users (under a guiding
hand) are the best people to write the documentation. 

I would be interested to weigh the number of bug requests in these areas
(improvements to documentation) against the number of emails sent to r-help.

One thing about the FAQ is the phrase "a command's intended definition may
not be best for statistical analysis" - It isn't clear what that means (or
the rest of the paragraph).

One thing I thing is really strange is that after clicking Help Pages
under the Documentation section of the R website menu (probably the first
place a new user would look), you are immediately told (in rather confusing
terms) to look elsewhere.

Just finding http://stat.ethz.ch/R-manual/R-patched/doc/html/ is quite a
challenge (and perhaps the wrong place to look too). By that stage I have
already been asked twice (in large bold letters, to contact the r-help
list). It is vital to help people navigate to the help material.

The first useful help material I found when I first turned to R was here
http://cran.r-project.org/doc/manuals/R-intro.html#A%20sample%20session

I think the website should make guiding people to their 'first steps' with
R much easier. As it is there is a confusion of help materials (is that
the correct collective noun?). NB: this isn't a 'bug report' about the
quality of the introductory material, which I think is very good, but
rather a feature request about the website and how people are guided to
that material.


Please kindly receive these suggestion in the spirit of their honest
intent which is to openly and scientifically promote thought and
discussion about the potential usability of R, its online resources and
its feedback mechanisms.

All the best,
Dan.