Feedback from vignette survey

January 8, 2012
By

(This article was first published on mages' blog, and kindly contributed to R-bloggers)

Many thanks to all who participated in the survey about writing R package vignettes.

Following my post last Thursday the responses came in quickly in the evening and all day on Friday. Since Saturday the response rate has been decreasing constantly and I think it is time for a summary based on the 56 responses received.

Summary - Things to keep in mind for a vignette

  • Length: Trust yourself, but aim for about 20 pages.
  • Language: Don't use language which assumes that the reader is an R and/or subject expert.
  • Structure: Include at least the following sections:
    • Examples
    • Introduction
    • Case studies
    • References
    It would be nice to include also sections on:
    • Support
    • Motivation
    • Road map
  • Examples: Use lots of examples and don't repeat just the examples from the help pages.
  • Get inspiration from: Rcpp, reshape, plyr, vegan, and see below for more.
  • Secrets of good vignettes:
    • Provide an introduction with a clear purpose of the package.
    • Work with case studies, walk the reader through a task from start to finish.
    • Demonstrate the non-default arguments of the package functions, highlight why and when you want to change them.
    • Write briefly and concisely, but provide reference/footnotes to relevant literature and further help.
    • Provide dummy data to play with.
    • Discuss limitations.
  • What else: Potentially split the vignette into several documents, see Rcpp for an example.

About the survey participants

  • Expertise: Most participants seem to be medium to advanced R users. This is not a surprise - how else would they know about my blog or R-bloggers? Over 50% write their own functions and a further 45% create R packages.
  • Usage of vignettes: Over 75% use them often (based on ratings with 4/5 or 5/5). Thus, vignettes are worth wile writing. They are often the starting point to learn more about a new package.
  • Writing experience: About 1/5 of the participants have written vignettes themselves and about another third have published papers, but not written vignettes or help pages.

Conclusions

This was an interesting experiment and I am really pleased with the turn out. The survey was completed by a good mixture of people, with varied experience and it showed the value of vignettes.

My big learning point is to focus more on the non-default arguments of the key package functions. I can see, that this really helps the reader to get a better understanding of the package and will help them to apply it better to their own problems and needs.

I was surprised by the relative high request for a support section in the vignette. Over 60% say that a support section would be at least nice to have. Even 14% think it is required. I wonder, if this means just an email address for questions, a mailing list, or commercial support. I would very much appreciate your feedback, either via email or comments below the post.

Charts

About the survey participants

R version 2.14.0 (2011-10-31) • googleVis-0.2.14 • Google Terms of Use • Data Policy

R code

You can access the R code for all charts via github.




To leave a comment for the author, please follow the link and comment on his blog: mages' blog.

R-bloggers.com offers daily e-mail updates about R news and tutorials on topics such as: visualization (ggplot2, Boxplots, maps, animation), programming (RStudio, Sweave, LaTeX, SQL, Eclipse, git, hadoop, Web Scraping) statistics (regression, PCA, time series, trading) and more...



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Tags: , , ,

Comments are closed.