Frank E Harrell Jr
fharrell at virginia.edu
Fri Jun 28 15:54:17 CEST 2002
Several people have posted very good thoughts on the issue of making R more "student friendly." My personal summary of these and what's needed, perhaps not just for students, is as follows. Emacs/Xemacs with ESS does part of this but non-everyday users need a simpler editor.
No point and click analyses- these instill bad practices and are not replicable. Even for drawing diagrams, command line applications can be far superior to point and click (see http://hesweb1.med.virginia.edu/biostat/teaching/statcomp/notes.pdf for examples using graphviz and LaTeX).
. Very friendly editor with syntax highlighting, auto-indenting, F1 key calls up documentation on object currently pointed to by cursor. If the object is the name of a common generic function (e.g., plot,summary,print,predict) a menu of available methods appears for user selection. Hitting F2 should bring up a skeleton function invocation (and perhaps do function name completion).
. Optional routing of output to a cumulative report window (Sweave should also be investigated here)
. Multi-tabbed graphics output window or separate process running a postscript viewer that is live-linked to the R session
and the most important features:
Extensive help tree with multiple views: (1) functions organized by key words; (2) functions organized by branches of statistics; (3) functions organized alphabetically; (4) statistical concepts [e.g., (a) group comparisons, each type such as two-sample comparison further divided into parametric and nonparametric; (b) regression, (c) EDA, ...]; (5) compendium by needed result; (6) manuals. For a basic stat class, view (4) needs to be prominent, and under each test or method there needs to be a representative example (e.g., for a Wilcoxon 2-sample test of y by levels of g type ..... but it's better to think of this as a special case of the Kruskal-Wallis test which may be obtained by typing .... or the Spearman test which may be obtained by typing ....).
For (6) there needs to be options to browse manuals on the web, to download them for future quick access, and to update already downloaded ones. A tree structure will help navigate manuals from different web sources. Links to such manuals need to be present for the other views. For (4) online case studies would be especially helpful (containing e.g., why a test was selected, graphical diagnostics for the test).
All trees need to be locally modifiable to add local sources. Each user-contributed package needs to have several hooks so that they are automatically pooled into the basic documentation.
A good overall approach for online documentation development might be along the lines of the Linux Documentation Project. There is something to be said for having a central web site developed and maintained by a group of volunteers ("Rdoc-core") for the documentation component that is not live-linked to the user commands. Components could be divided up and refined over time by individuals, and perhaps linked to comments/criticism from others. Imagine just hitting the "Reload" button on your browser to get improvements in the docs or to get new comments/examples/warnings/simulations/references posted by other users.
I'm sure others will have many improvements to this sketch if the overall approach is worthwhile.
Frank E Harrell Jr Prof. of Biostatistics & Statistics
Div. of Biostatistics & Epidem. Dept. of Health Evaluation Sciences
U. Virginia School of Medicine http://hesweb1.med.virginia.edu/biostat
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
More information about the R-help