tutorial.helpers provides functions and RStudio Addins to help you write R tutorials, especially if you follow my advice about the best way to do so. This approach is currently used in two packages: primer.tutorials and r4ds.tutorials.
To install the package from CRAN:
install.packages("tutorial.helpers")You can install the development version from GitHub with:
remotes::install_github("PPBDS/tutorial.helpers")The most useful tool is the download
answers trick. In your tutorial, simply include
library(tutorial.helpers) in the setup R code chunk and
then insert this empty code chunk at the end.
```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```This will ask the student to provide an estimate of how long the tutorial took to complete. It will then provide the ability to download the student’s answers in html format. Students submit these files to their instructors, who can then confirm that the work was completed and look for any patterns in student (mis)understandings.
There are three exported functions for checking the tutorials in your package. See the testing vignette for details on their use.
We recommend including this child document at the start of each tutorial:
```{r info-section, child = system.file("child_documents/info_section.Rmd", package = "tutorial.helpers")}
```This will insert (optinal) questions asking for the student’s name, email and id.
We also recommend including this at the beginning of your tutorial:
```{r copy-code-chunk, child = system.file("child_documents/copy_button.Rmd", package = "tutorial.helpers")}
```This allows you to place a button in an exercise which will allow students to copy over all the code from the previous exercise. Use:
<button onclick = "transfer_code(this)">Copy previous code</button>This is handy for students when a series of exercises requires them to build up a long pipe, line-by-line.
We recommend ending the tutorial with the download-answers child document, as discussed above.
```{r download-answers, child = system.file("child_documents/download_answers.Rmd", package = "tutorial.helpers")}
```In order to access the addins, load the package. See the addins vignette for details about their use.
The package includes a tutorial, “Getting Started with Tutorials,” which provides an introduction to tutorials for beginning students. You should require your students to complete this tutorial if you are using tutorial.packages to create your own tutorials.