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: [EMAIL PROTECTED]
______________________________________________
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.
