[R] Great R documentation
Karl Ove Hufthammer
karloh at mi.uib.no
Mon Jul 31 11:42:47 CEST 2006
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: karl at huftis.org
More information about the R-help