Chapter 3 Lessons

Lessons lay at the heart of your teaching. But between where you start and where your learners end up, there is a lot of work. Foremost in your head at the start may be the delivery method, like whether you are preparing a workshop, a self-paced online tutorial, or an academic course. We want to offer you a different mindset, and that is to mentally separate your content from your delivery, i.e., what content is delivered is distinct from how it will be delivered.

But first, a very brief history of “literate programming” (and why you are a literate programmer).

3.1 A very brief history

The concept of “literate programming” was originally introduced by Donald Knuth in 1984. In a nutshell, Knuth envisioned a new programming paradigm where computer scientists focus on weaving code together with text as documentation, with the aim of creating software programs as “works of literature.”

Knuth coined this new paradigm the WEB system, which you have probably never heard of! But lucky for all of us, Knuth took the important steps to write down and publish his vision for the WEB. By doing that, he inspired software developers to not only change their own mindset, but to change their toolsets too: they created tools to enable others to write literate programs.

Then, some developers created tools to enable others to write better literate programs; they realized that it would make sense for users to write their narratives in a markup language made for authoring (such as Markdown or \(LaTeX\)). This advance made it easier and ultimately natural to use real words in full sentences, instead of just adding comments to code.

Now, take those mindset-changing tools, make them actually accessible to people other than software developers, and that is where we sit today. You are reading a book that was created by non-software-developers who wrote text in Markdown combined with R code and:

The toolchain may sound complicated at first, but this wasn’t our first rodeo. We worked up to using and integrating all these tools, building up from the basics of literate programming using tools we already knew. Most importantly, each link in our toolchain has improved our collective quality of life as collaborators:

  1. We can share our ideas better with each other because we can see each others’ ideas easier.

  2. We can share our ideas better with each other because we can share our code easier.

  3. We can share our ideas better with everyone else because we can share our website easier.

Even if you only have one collaborator and that person is yourself, we think these payoffs will apply in your life as an educator. Certainly, the idea of applying literate programming principles to teaching programming is not new. Lots of well-respected educators have written But, we think that opening up literate programming toolkits for educators with specific use cases may be new- in our experience, the actual application of using literate programming tools.

The most fully-featured tool for literate programming in the R ecosystem is R Markdown. But, this is not a chapter about R Markdown (see the cookbooks later for those). This is a chapter to get you thinking about lesson development workflows, and how to design your own. Our goal is to arm you with information and intellectual fuel to want to apply literate programming principles to lesson-making, from lesson design to delivery.

“There is no telling what will happen if lots of other people catch WEB fever and start foisting their creations on each other.”

— Donald E. Knuth, Literate Programming, 1984 (edited by the authors)

3.2 A very brief pep-talk

You may not need to hear this, because you may be reading this and already using R, RStudio, GitHub, and other advanced tooling for education. If so, kudos to you! You have grit and it shows 🎉. But, if you are not this kind of educator (yet!), please read on…

but we encourage educators to step back for a moment, and think about the things that are hard about your current teaching workflow, and to reasonably weigh the pros and cons of adopting new tools and workflows. Let’s start with a few “truths”:

Still life of a sad course

Figure 3.1: Still life of a sad course


Still life of a happier course

Figure 3.2: Still life of a happier course

  1. Educators create a lot of files:
    • outlines,
    • slides,
    • assignments,
    • activities,
    • scripts,
    • data,
    • plots,
    • images,
    • screenshots,
    • your 2015 taxes (kidding, sort of).


    The natural consequence of not having a workflow for organizing these files is “course chaos”, otherwise known as content that is hard to update, share, and deliver (see Figure 3.1).


    Contrast this with a happier setup (Figure 3.2), where you can find, edit, and remix/reuse/recycle your own code and words easily. The file structure pictured is from an R Markdown website, which leaves a lot to be desired in terms of file organization, but is often “good enough” to get the job done (and to improve the educator’s quality of life dramatically).



  2. You are more than your teaching materials.

    You may feel like “I can’t simply put all my materials online! Will my students still come to class? Will my employer take them and leave me behind in the dust? Will other people steal my ideas?”


  3. Baby steps

    You don’t need to use all the tools. But, be open to when opportunities arise that challenge your current skillset and provide an “excuse” to level up your skills.

3.3 Literate lesson-making

“Programming Teaching is a very personal activity, so I can’t be certain that what has worked for me will work for everybody.”

— Donald E. Knuth, Literate Programming, 1984 (edited by the authors)

Permission to educators who teach R or teach with R to consider themselves literate programmers. You are programming a lesson, however you end up delivering it. You could deliver a lesson any number of ways, but you are a literate programmer. For any given lesson, here are some “inputs” that you need to design around:

  • Audience: who are your learners?

  • Time: how long do you have with the learners? If you won’t meet them in person (i.e., you are designing a ), this is trickier- you need to think about how long you can reasonably have their attention for.

  • Scope: what are your learning objectives?

  • Sequencing: in what order can you cover the things you need to meet your learners’ goals?

  • Medium: how will you deliver your lesson?

If you would like pedagogical advice for how to plug in these inputs, and get a lesson out, there are many ways to get there but we recommend following Greg Wilson’s advice for A Lesson Design Process, from his book Teaching Tech Together.

3.4 Make it work

3.4.1 Make it work for you

You know the rule for putting your own oxygen mask on first, before helping others? Same goes for lesson development. Whatever tool you choose to use, it should be one that works for you, first and foremost. If you hate working with X tool every time you open it, you’ll hate working on your content period. And that is not a good place to be.

3.4.2 Make it work for them

3.5 Literate lesson-delivery

involves letting your learners easily access, manipulate, and otherwise “play with” your learning content. You should think about when and how much play you want to encourage…

3.6 Literate lesson-sharing

put it all on github, yes reasons:

  1. for you- easier to work on
  2. for you- lets you see holes
  3. for them- lets them see your vision
  4. for them- can reduce reliance on actual vision
  5. for us- lets the community learn from you, even if they weren’t the ones you designed the content for
  6. for future you- lets you build a network, prof development

3.7 Sample Rmds

MoMA lab
NHANES workshop

3.8 Sharing

3.8.1 Share source code

  • first, know the knitr code chunk options, and remember about code folding.

  • GitHub to view source (but not very readable, see next section)

  • code download

3.8.2 Share readable output

What if you just want to keep things really simple? Try github_document as the output of a regular R script. This will create an .md version of whatever code and output you have, and it will be rendered in a nice, readable way without you having to mess with GitHub pages or HTML directly, etc. See an example of what I mean below:

Start with .R script… and …end with a GitHub document

Can also export to pdf as attachments

3.9 Lesson delivery & sharing

When it comes to presenting your lesson, here are some things to consider and tool recommendations for different lesson delivery methods.

3.9.1 Live coding

  • Start with R Markdown
  • Disable all custom RStudio color themes and fonts
  • Keycastr
  • In case of catastrophe, test out Loom

3.9.2 Screencast

  • getkap, Quicktime
  • Start with R Markdown
  • Keycastr
  • web hosting

3.9.3 Online tutorials

  • web hosting
  • html widgets like plotly, highchartr, etc.
  • learnr tutorials

3.9.4 Remote workshops & webinars

  • Zoom with break-out chat rooms
  • Google docs
All illustrations CC-BY-NC : You can download them by clicking here
All other materials CC-BY unless noted otherwise.