Tutorials for Books

This vignette assumes that you have already read our advice about writing good tutorials.

A common use case for this package is to write a collection of tutorials for a book. Consider the r4ds.tutorials package which is a companion to R for Data Science (2e) by Hadley Wickham, Mine Çetinkaya-Rundel, and Garrett Grolemund.

Instructors like to assign books with code. Ideally, we want our students to read the book, working through the included code, line-by-line. Sadly, very few students are so disciplined. In fact, in a large class, a majority of the students won’t even read the book.

The tutorial.helpers package makes it easy to create a structured tutorial in which students type in (almost) every command which the book demonstrates, along with other commands which, in your judgment, are helpful.

Consider some idiosyncratic advice for book-based tutorials using the example of R for Data Science (2e) and r4ds.tutorials.

Do one or two of the tutorials before you start working on your own.
Make your Introduction look like this:

This tutorial covers [Chapter 20: Spreadsheets](https://r4ds.hadley.nz/spreadsheets.html) 
from [*R for Data Science (2e)*](https://r4ds.hadley.nz/) by Hadley Wickham, 
Mine Çetinkaya-Rundel, and Garrett Grolemund. You will learn how to get data from Excel 
spreadsheets using  `[read_excel()](https://readxl.tidyverse.org/reference/read_excel.html)` 
from the [**readxl**](https://readxl.tidyverse.org/) package and Google sheets using
`[read_sheet()](https://googlesheets4.tidyverse.org/reference/range_read.html)` from 
the [**googlesheets4**](https://googlesheets4.tidyverse.org/) package.

The first sentence provides a link to your chapter as well as to R4DS.
We highlight some of the most important packages and functions used in the tutorial.
We don’t go overboard. You can’t mention every package or every function used in the tutorial.
Make your Summary look like this:

This tutorial covered [Chapter 20: Spreadsheets](https://r4ds.hadley.nz/spreadsheets.html) 
from [*R for Data Science (2e)*](https://r4ds.hadley.nz/) by Hadley Wickham, 
Mine Çetinkaya-Rundel, and Garrett Grolemund. You have learned how to get data from Excel
spreadsheets using  `[read_excel()](https://readxl.tidyverse.org/reference/read_excel.html)` 
from the [**readxl**](https://readxl.tidyverse.org/) package and Google sheets using
`[read_sheet()](https://googlesheets4.tidyverse.org/reference/range_read.html)` from 
the [**googlesheets4**](https://googlesheets4.tidyverse.org/) package.

Read “[Data Organization in Spreadsheets](https://doi.org/10.1080/00031305.2017.1375989)” 
by Karl Broman and Kara Woo for great advice about organizing your data using spreadsheets.

The first paragraph is identical to the Introduction, except that “covers” is replaced with “covered” and “will learn” with “have learned.” We began the tutorial with a promise about what students would learn. One hopes that we kept that promise.
The second paragraph gives one or two pointers about the best material which a student might look into if she is interested in learning more about the broad topic of the tutorial. These pointers were also mentioned as knowledge drops earlier in the tutorial.
These pointers will often (always?) be items which were mentioned in the book itself. Those authors, presumably, have good taste, otherwise you would not have selected their book in the first place.
Always have a separate Exercise for each library you load and each data set you use. An Exercise like “Load the tidyverse package with the library() command.” is, obviously, not difficult for students. But it forces them to practice loading libraries, which many students forget, and it provides us with an opportunity to drop some knowledge.
Regularly require them to look up the help page for a function, proving that they have done so by copy/pasting a portion of the help page, which means that these will be Exercises with No Answer instead of Code Exercises. Students need to get in the practice of using help.
You want students to have to type in at least 90% of the code which is used in the book. One approach is to first, set up a bunch of empty Code Exercises. Then, go through the chapter, copying each snippet of example code into the Test chunk of an Exercise. (If the book is sourced freely, you can also copy/paste a knowledge drop associated with each code snippet.) Then, go back and write the Exercises such that the answers are the code snippets from the book. The final step is to copy the code to the Hint chunk, and then edit out at least a portion of that code.
In most books, the authors will include more than one new thing in each code example. They will add two or three lines to a pipe or pass in two or three arguments to a function. We never want to go that fast. Spread out such code snippets into two or three separate Exercises, each of which makes the smallest possible change. We are building the shallowest possible learning curve.
Recall the distinction between books which have a permissive license, meaning that we can copy/paste text at our own discretion, and those which do not. For the latter, you can not copy/paste text. But you can express, in your own words, the key points made in each chapter. In either case, your knowledge drops should cover the most important things for students to know, in your opinion, among those topics covered in the chapter.
A common annoyance is the creation of temporary objects. Consider this code snippet from R for Data Science.

x <- c("$1,234", "USD 3,513", "59%")
parse_number(x)
#> [1] 1234 3513   59

It is unclear how to create x in your tutorial. You could have an Exercise in which the students create x themselves. But that is annoying because it doesn’t really teach students anything. It is too close to busy work. Moreover, x won’t exist for the next question, requiring the use of parse_number(). You will need to create x yourself, either in the global setup chunk or in a setup chunk for this Exercise. The global setup approach is preferred, but does not work if there are multiple different x objects used in this chapter.
I recommend just including the “busy work” in the Exercise code chunk when writing the tutorial, followed by a blank line, so that students have an obvious place to type in parse_number(x).

x <- c("$1,234", "USD 3,513", "59%")

This avoids the complication of creating/maintaining a bunch of temporary variables. It also means less busy work for students.

David Kane