Re: [R] Great R documentation

From: Karl Ove Hufthammer <karloh_at_mi.uib.no>
Date: Mon 31 Jul 2006 - 19:42:47 EST

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@huftis.org

______________________________________________
R-help@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
Received on Mon Jul 31 19:59:12 2006

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.1.8, at Mon 31 Jul 2006 - 20:33:53 EST.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.