[R] Great R documentation

[Karl Ove Hufthammer]

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