Dear all, Many thanks to all who replied to my message. Here follows a summary of the most important points to me. 1. There seems to be a general agreement on a need for docs for non-statisticians with respect to two points: (i) explaining how to get first in R for those who are not used with command-lines, object-oriented languages, loops, ... and (ii) illustrating to the various specialists how they could use R to do the analyses or tests which are common practice in their field. 2. There is a need to translate docs (and this has already started in Japanese). This could concern only the non-technical materials, as statisticians, mathematicians ... generally read English. It appears that significant materials probably already exist in various files, folders, ... around the world, so trying to fill the above needs may be carried out by putting together efforts that have already been done. Here are my (vague) suggestions on the objectives relative to the above needs. 1.i. Writing a simple and short tutorial on how to do basic things in R (read data, plots, graphs...); also emphasize on the advantages of R compared to softwares with pull-down menus. 1.ii. This could take 2 forms (but not mutually exclusive). First, write tutorials explaining how to do the usual stats in a given field, this could be appended to the above doc with chapters like "R for biologists", "R for psychologists", ... Second, write packages similar to Doug Bates' Devore5, but referring to the handbooks that are popular in other fields (for instance, Sokal & Rohlf's "Biometry" is very popular among my colleagues). 2. Probably what is proposed above would be worth translating... but it still needs to be written (... in any language). The "Introduction to R" at least already exists, but (looking at it closely right now...) it is quite a dense document and I have no idea on the time required to translate it (it depends on the language it is translated in I suppose). On the other hand, if it has already been translated in Japanese then it could be worth doing it with other languages. There is a (probably less urgent) need for advanced users on how to write new R functions, more advanced R features... Brian Ripley mentioned that an R Language Manual is planned, and the last book by Venables & Ripley treats R as one of three dialects of the S language. Again, these are simply suggestions, and I would be glad to discuss them. I am, of course, volunteer to contribute to docs and others mentioned they are as well. No doubt there will be enough enthusiasm among R users to carry out the task. Finally, many thanks to Friedrich Leisch for his proposal to create a ``contributed documentation'' section on CRAN. Best wishes to all, Emmanuel Paradis -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
R Documentation(s) -- Summary
2 messages · Emmanuel Paradis, Ko-Kang Kevin Wang
2 days later
Emmanuel Paradis wrote:
Dear all, Many thanks to all who replied to my message. Here follows a summary of the most important points to me. 1. There seems to be a general agreement on a need for docs for non-statisticians with respect to two points: (i) explaining how to get first in R for those who are not used with command-lines, object-oriented languages, loops, ... and (ii) illustrating to the various specialists how they could use R to do the analyses or tests which are common practice in their field. 2. There is a need to translate docs (and this has already started in Japanese). This could concern only the non-technical materials, as statisticians, mathematicians ... generally read English. It appears that significant materials probably already exist in various files, folders, ... around the world, so trying to fill the above needs may be carried out by putting together efforts that have already been done. Here are my (vague) suggestions on the objectives relative to the above needs. 1.i. Writing a simple and short tutorial on how to do basic things in R (read data, plots, graphs...); also emphasize on the advantages of R compared to softwares with pull-down menus.
As an undergraduate student who has only been using R for 2 years, I feel that I am quite suitable to comment on this proporsal. By now I consider myself an intermediate R user, and even so I sometimes still forget some basic things in R. However, almost all of the time I can find what I want by using the R Documentation Manuals (by typing ?function_name). I actually think the R help file has already contained quite enough [basic] information for beginners, it even explains each argument in a function. Therefore, I personally think the R Manual (or what I call the R API) is sufficient enough. If, for example, a newbie wants to find how to use the plot() in R, he/she can simply type
?plot
then there are lots of help and hints there! The next step he/she should do is go through each example line by line, to see what each line does. Then perhaps creat his/her own example, say:
x <- 1:10 plot( x ) plot( x, main = "Test", xlab = "Index", ylab = "foo" )
. . . To me, when I was a newbie, I found this is the best technique.
1.ii. This could take 2 forms (but not mutually exclusive). First, write tutorials explaining how to do the usual stats in a given field, this could be appended to the above doc with chapters like "R for biologists", "R for psychologists", ... Second, write packages similar to Doug Bates' Devore5, but referring to the handbooks that are popular in other fields (for instance, Sokal & Rohlf's "Biometry" is very popular among my colleagues).
In fact, I've got bits and bits examples and tutorials on "R for Mathematicians", "R for Econometricians" and "R for Statisticians". However some of them are quite short (approx 5 pages) and I don't think they are worth contributed at this stage. I may add a bit more things to it. By the way, does anyone know if there is a "R for Computer Scientists" tutorial or documentation around?
2. Probably what is proposed above would be worth translating... but it still needs to be written (... in any language). The "Introduction to R" at least already exists, but (looking at it closely right now...) it is quite a dense document and I have no idea on the time required to translate it (it depends on the language it is translated in I suppose). On the other hand, if it has already been translated in Japanese then it could be worth doing it with other languages.
In fact, I have volunteered to translate "An Introduction to R" into Chinese Traditional. However, I'm a bit disappointed that nobody have replied to me that they are willing to help me. I am very sure there are lots of Chinese users out there, do they/you think a Chinese translation is not needed?
There is a (probably less urgent) need for advanced users on how to write new R functions, more advanced R features... Brian Ripley mentioned that an R Language Manual is planned, and the last book by Venables & Ripley treats R as one of three dialects of the S language. Again, these are simply suggestions, and I would be glad to discuss them. I am, of course, volunteer to contribute to docs and others mentioned they are as well. No doubt there will be enough enthusiasm among R users to carry out the task. Finally, many thanks to Friedrich Leisch for his proposal to create a ``contributed documentation'' section on CRAN. Best wishes to all, Emmanuel Paradis -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
-- ----------------------------------------------------------------------------------- Ko-Kang Wang Undergraduate Student Computer Science/Statistics Double Major University of Auckland Auckland 1005 New Zealand ----------------------------------------------------------------------------------- -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.- r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html Send "info", "help", or "[un]subscribe" (in the "body", not the subject !) To: r-help-request at stat.math.ethz.ch _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._