Re: [R] Great R documentation

From: Karl Ove Hufthammer <>
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!


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 ...


Instead, start with:




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:


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:

______________________________________________ mailing list
PLEASE do read the posting guide
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 Please read the posting guide before posting to the list.