Teaching R Programming Using R Markdown Notebooks

In January I wrote about using Macdown to write in Markdown, a convention for writing in plain text while encoding the structure of your document—headers, block quotes, lists, footnotes, etc.—using simple typographic characters. If you’d like to learn more about the convention or what other Profs. Hacker are doing with it, we have a substantial archive of Markdown posts to browse. After writing that post, however, I realized there’s one other application I use to write in Markdown and one other significant use to which I put Markdown.

In several of my classes, such as Technologies of Text, I teach students the basics of programming for computational text analysis. I use the R programming language: not out of any philosophical commitment to it over, say, Python, but because I learned programming amongst data scientists who preferred R. We work in RStudio server, so that I can control all of the settings and packages (like plugins) installed for students. For many years, though, I struggled a bit with the best way to present code to mostly humanities students, many of whom have no experience with—and often anxiety about—coding. I find most print and online R textbooks opaque and alienating for humanities students as well. When the first lesson asks students to create a calculator rather than, say, work with text, it can be difficult for humanities students to immediately see how coding might be pertinent to their domain. I needed a way to create custom lessons.

Enter RMD, or R Markdown, an adaptation of Markdown that allows users to write notebooks that weave together prose—tagged using Markdown syntax—and executable blocks of code. I learned about RMD from a colleague who was writing all of his programming lessons as RMD notebooks. I knew immediately that these notebooks were the solution for programming lessons in my class. I can write my own prose, directly pertinent to the material in our class, building in pre-written blocks of executable code that would demonstrate key programming concepts for students. In addition, I can build in incomplete or blank code blocks that students can use to write their own code. By integrating prose and code, RMD also gives students a way to see immediate relationships between programming and writing, which I find is a boon for humanities students taking their first steps into coding.

I don’t have space in this post for a full RMD tutorial, though if there’s enough interest among readers perhaps I can plan a series along those lines. There’s a good starter tutorial here. I’ll also add a link to one of my RMD files for an undergraduate class, which walks through setting up a Mad-Libs style Twitter poetry bot, and a series of RMD files for my graduate class in data analysis using R. You should download these files to open in RStudio or click Raw to see their RMD code. For this post, I simply wanted to highlight the idea of literate programming and point to another important application for Markdown. If you teach with R (or are thinking about doing so), RMD is a powerful tool for developing customized lessons for students at any level.

Do you teach programming in your classes? If so, do you have a favorite method for teaching it, or tool helping your students understand and write it? Tell us your favorites in the comments?