README.md vs package vignette vs ?package documentation

Package development
3

This is indeed something I also always found a bit tricky and had a hard time finding a solution I liked.

The following is the solution I came up with when I started developing packages and I've stuck with since (there are other ways to handle it, but this is what I found works for me and my users). I'm open to changing my workflow if I see other good ideas in this discussion.

Overview

My philosophy is to have a fairly detailed README because many people find a package through github, and the README is the first thing you see there. It's very possible that I'm biased because I spent so much time in the R twitterverse which is very github friendly, and I've been heavily influenced by people like @jennybryan, so I always gravitated towards making the package documentation very github friendly. It's important for me to have the README act as a good intro to the package. The README also gets shown on other websites like CRAN, rdocumentation.org, METACRAN , etc. So I really care about a good README!

My second thought is that I also want to make sure every package has a main vignette. This main vignette should be very similar to the README. In fact, it should be essentially identical. So that's what I did - I wanted to be able to create both my main vignette and my README from the same source.

Next, if the package has some more specific vignettes for advanced or specific usecases, those can be vignettes as well, and I make sure to link to them from the main vignette/README.

Finally, you mention the ?package documentation. I personally never use them, but I did want to make sure my documentation is complete, so I include a short description in there and include a link to the full REDME.

Implementation

I'll show an example of how I do my documentation workflow with my package shinyjs.

  • I create the main vignette and name it <packagename>.Rmd, and I make it fairly details to explain the package, its usecases, and show examples. shinyjs example

  • I want to create my README from the same vignette, but I don't want to have to copy it manually because then I run into the possibility of forgetting to update either the vignette or the README. I wanted a solution that makes sure they're both in sync. Another small problem is that the file paths in this vignette would not work properly in the README because they're not in the same folder (image paths, links to other vignettes, etc.). So I created a Makefile that automatically creates my README. shinyjs example

  • When I want to update my README, I only update the shinyjs.Rmd vignette, and then I run make in a shell. It's super easy. I literally open up a shell in the package's root directory, run make (this works for both unix and Windows), and that's it, it'll create a README file from my vignette and correct all the paths.

  • If I need to have a few more vignettes, I make sure to link to them from the README/main vignette so that they're easy to find, because most people wouldn't know to search for vignettes. shinyjs example

  • I also create a file named <packagename>.R in the R/ folder, and make a @docType package to document the package. I personally think the value of this is fairly low (I might be wrong), but I do it anyway. I copy the description from the DESCRIPTION file, and at the end I add a link to the README. shinyjs example

I've actually been meaning to write a blog post about this soon so this was helpful to get down on paper. Now people can also critique my method and tell me how needlessly complicated or silly it is :slight_smile:

I hope this helps!

10 Likes