mages' blog

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 - How to write a good 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.
  

I am currently co-writing the vignette for the ChainLadder package and wonder what I should be focusing on. I have co-written the vignette of the googleVis package in the past and based it purely and what I thought would work. So, this is an experiment to find out, if user feedback will help me to write a better vignette. Let's see how it develops. I will make the data available once I have at least 10 submission.


Thanks!