Dear all, I'm trying to improve the documentation I provide my R packages, and to that end I'd like to find out what you think is great R documentation. I'm particularly interested in function documentation, but great vignettes, websites or book are also of interest. What is your favourite bit of R documentation, and why? Thanks, Hadley
hadley wickham skreiv:> I'm trying to improve the documentation I provide my R packages, and > to that end I'd like to find out what you think is great R > documentation. I'm particularly interested in function documentation, > but great vignettes, websites or book are also of interest. > > What is your favourite bit of R documentation, and why?I find that a graphic is worth *at least* a thousand words. I learn very much from looking at examples of the graphical output of functions, and it?s often much easier to look through ?example(function)? for a output that looks similar to what I need, and to tweak it, than to read the documentation to find out how to create the needed graphic (if it?s possible at all). And it?s fun too! Example: demo(graphics) and library(lattice) example(xyplot) These beautiful and interesting graphics. My advice will therefore be to document every function with plenty of interesting and useful and different (trivial variants on a graphic is not interesting) and *pretty* examples. And do not start the examples section with a very advanced example, with many parameters and based on many transformations of a data set. For example, do not write: ... 10 impossible-to-understand lines for generating or transforming the data set ... fancyPlot(x,y,data=foo,lw=3,rty=2,bw="full",qrs="partial",method="bayes", nw="bar",clp=list(open.edge=TRUE,col=1,doubleMar=list(type="tr")), compute=c("o","p","lower","upper"),cex=1.2,xlim=range(x)*1.3) Instead, start with: fancyPlot(anscombe) or x=rnorm(100) fancyPlot(x) Then gradually make the examples more advanced or complete. And do document/comment the examples. Say what?s going on, what the graphic (or table, or textual output) shows and why it?s interesting. One more thing: The ?lattice? package also has a nice introduction: ?Lattice I believe all packages should have such a introduction, to give an overview of the package, what it?s about and some examples of use. One last advice: If you have a vignette or a demo, do tell in the ?Description? of ?library(help=package)?. It?s *very* easy to miss otherwise (and many people don?t know that demos or even vignettes exist). -- Karl Ove Hufthammer E-mail and Jabber: karl at huftis.org
At 10:09 31/07/2006, hadley wickham wrote:>Dear all, > >I'm trying to improve the documentation I provide my R packages, and >to that end I'd like to find out what you think is great R >documentation. I'm particularly interested in function documentation,Hadley, I do not think any bit of function documentation, if you mean the manual page type documents, is ever that enlightening unless you already know what the function does. For me the useful documents are the more extended narrative documents. What I find helpful is: start with what is the aim of this document tell me what I am assumed to know first (and ideally tell me where to look if I do not) start with an example using the defaults tell me what the output means in terms of the scientific problem tell me what action I might take when it gives me a warning (if that is predictable) tell me about other packages with the same aim and why I should use this one tell me where to go for more information>but great vignettes, websites or book are also of interest. > >What is your favourite bit of R documentation, and why? > >Thanks, > >Hadley > >Michael Dewey http://www.aghmed.fsnet.co.uk
--- hadley wickham <h.wickham at gmail.com> wrote:> Dear all, > > I'm trying to improve the documentation I provide myI am a new user and at moment I am finding "An Introduction to S and the Hmisc and Design Libraries? by Carlos Alzola and Frank E. Harrell is very helpful as it explains some "simple" data manipulations that other documentation seems to assume one will know. My opinion is that much of the documentation is very good but very terse and at least in the help files sometimes a bit too clever. There seldom seems to be enough explaination as to why something does something which has often left me able to do exactly what I want to do but having a difficult time generalizing. Of course, if I could track down whoever at my local university has taken out all the R books I might be much better off. :)