Why and How to Include a Vignette in Your R Package

R's function documentation is well-known and widely used, explaining function usage, parameters, and giving examples. However, if you don't know a package yet, reading help pages about functions may be too specific - you may want to know at a more general level which kinds of tasks the package was designed for, and get a general introduction.

This is where vignettes shine. They are created using R Markdown, allow you to write arbitrary text, and mix that with R code. A huge advantage compared to function documentation is that the reader doesn't need to actually run the R code to see what it does. Instead, the vignette contains the results that the R code produces. So the user doesn''t need to clean up the Global Environment when the code creates objects.

Examples for thorough documentation via vignettes are the dplyr and data.table packages. You can run

help(package = "dplyr")
help(package = "data.table")

to get to an overview page, and click on "User guides, package vignettes and other documentation" to choose from the vignettes these great packages offer.

To find out more, read the great R Packages book by Hadley Wickham and Jenny Bryan: https://r-pkgs.org/index.html

Contact me, e. g. to discuss (online) R workshops / trainings / webinars:

LinkedIn:   / wolfriepl  
Twitter:   / statistikindd  
Xing: https://www.xing.com/profile/Wolf_Riepl
Facebook:   / statistikdresden  

https://statistik-dresden.de/kontakt
R Workshops: https://statistik-dresden.de/r-schulu...
Blog (German, translate option): https://statistik-dresden.de/statisti...

Playlist: Music chart history
   • Music Chart History