Hey everyone, beginner to R. I think I understand the difference between documentation and vignettes, but I'm not sure. To my understanding, vignettes are basically just longer, more detailed versions of documentations. Also, vignettes are centered around an overall package, whereas documentation is great for specific function help, pieces of code, etc. Can someone confirm this? Thank you.
Help files, vignettes and articles all belong to the documentation with small differences in usage and purpose.
Help files are function-oriented. They are specific instructions of one or a couple of related functions. They usually detail the technical features of a function with a short description about what the function does and the available parameters (if there is any), some basic examples and the value returned.
Vignettes and articles are more package oriented and can be defined as a guide on how to use a package. They often describe the goal of a package, give an overview about what the package does, the function it contains, in-depth explanations and examples. That said they can be about anything really.
Articles differ from vignettes in that they don't ship with the package so they are only accessible on independent documentations such as a pkgdown website.
2 Likes
Thank you for the response! Just to clarify: by "help files", are y0u referring to the "Help" tab in the R desktop interface?
Help files are the documentation that one usually accesses via ? or help(). In RStudio, help files will show up in the Help tab but that documentation is also accessible on a pkgdown website for example.
1 Like
Great answer, just a nitpick: articles and vignettes are usually the same content.
Historically, R calls it "vignette". But the name seemed unsuited for a web page, so pkgdown (the package many people use to create a website for their package) decided to call it "article". But the articles are built from the same code as the vignettes.