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

From: <dmb_at_mrc-dunn.cam.ac.uk>
Date: Mon 08 Nov 2004 - 01:14:27 EST

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,

R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon Nov 08 01:21:09 2004

This archive was generated by hypermail 2.1.8 : Mon 08 Nov 2004 - 02:12:32 EST