Desiree De Leon | Of Teacups, Giraffes, and R Markdown | RStudio (2020)
How do you make your R Markdown lessons feel friendly for learners you’ll never meet? How do you make it engaging so they sit and stay a while? How do you make it memorable so they come back to visit again? In this talk, I’ll share lessons learned from my experience of making a series of online statistics modules (co-authored by Hasse Walum) that feel accessible and fun-- housed entirely in an R Markdown site, complete with a whimsical, illustrated narrative about teacup giraffes. I’ll show how adding good characters with your audience in mind, good design, and good play helped me make the most of HTML output. To help you get started, I’ll share resources that Alison Hill and I have developed--including a series of cookbooks and out-of-the-box templates-- so that you will have a leg up on applying these ideas to R Markdown collections of your own
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
Okay, I am so excited today to talk to you about teacups, giraffes, and R Markdown. My name is Desiree De Leon, and today I'm going to be talking to you about a project that I worked on with my co-author, Hassa Wallam, last year to make teaching and learning statistics a little bit more inviting, fun, and intuitive, and this was all done using only an R Markdown website.
So my goal here today for the next 15 minutes is to kind of give you a quick tour around this project and hopefully give you some ideas for what's possible with HTML output of R Markdown so that you can incorporate some of these things into your own materials in the future.
The problem: making statistics engaging
When teaching something that has the potential to be a little bit dry, what is it that makes it difficult to motivate learners? Within our own local academic circles, Hassa and I had gotten the impression that many people saw statistics as either something unintuitive, scary, or very boring, and we wanted to see if we could do something about that.
So we thought, let's teach a really cool stats seminar at our university, and we were pretty excited about this idea, but for reasons of red tape, our idea for teaching got squashed, but we decided that we still wanted to make that content and put it online.
But then that introduces a second problem, which is that we now lose that precious face-to-face time with students in a classroom that usually adds an additional hurdle for engagement, unless we could come up with a way to keep that content compelling. And so we thought that we could try this by nesting our statistics lessons inside of a story, and we all know that for a good story, you need good characters.
Good characters: the teacup giraffe
So really early on in our process, we started to brainstorm some heroes that could play the protagonists throughout our statistical content that we were going to be building. And ultimately, we came up with the teacup giraffe, which is our fictional little species named for its tiny stature.
And so now we had this hero for all of our stats modules, and we could begin to make up data about it and build a story around it, and so I just want to give you a small sampler of what this narrative is like.
So there are two distinct populations of teacup giraffes, each inhabiting their own remote islands. And as the learner coming to our site, you play the role of the graduate student, and you've been tasked with collecting data about this mysterious little species, which the most sought-after data is about their height, which on both islands is variable. Teacup giraffes also really love eating celery. So by assessing how much of it that they eat, you now have an additional variable to measure. And all the while that you're collecting this data, you deal with really demanding emails from your advisor back at home, who needs GG plots and other results for these data, and he needs them now.
But hopefully, teacup giraffes make that a little bit less stressful.
So with this, now you've gotten a little bit of a sampler of the teacup giraffe's world, and this is actually what served as our backdrop for our equations, our code, and all of our exercises that we built. And actually, we went a little bit overboard in creating this world, because we wrote an entire backstory that was completely separate from the stats content, and it's all about how the giraffes were discovered, a little bit about their silly behavior. And at this point, you're probably thinking it's reaching the level of absurdity, and I actually agree with you.
But we hope that all of this storyboarding would really help to suck learners in, and not only learners, because as content creators, we also got sucked into the teacup giraffe world, quite literally.
Okay, but silliness aside, if you do have some creative muscle that you'd like to flex, then creating your own good characters is a great way to do that with your educational content. All of the character elements that I've shown you so far here are illustrations that I made on an iPad Pro using the Procreate app, but in case drawing your own characters is not a possibility, there are many other resources where you can find really great high-res and open-source images, and one of those is unsplash.com, so I point you there for really strong visuals.
Okay, so usually at this point of introducing the project to someone, most people think that we've actually made a children's book and not a stats website. But our teacup giraffes do have some more utility than just ramping up the delight meter. We specifically created our character with our lessons in mind, so in particular, we could make things like statistical concepts, like the variance, a little bit less abstract, because not only do our teacup giraffes provide strong visuals for word problems, like, for example, asking what percentage of giraffes in our population will be shorter than this little guy here, but maybe a more subtle benefit is that we can use our character to link to otherwise less intuitive concepts. For example, by using the spots, the color of the spots on our characters to show and illustrate the concept of the sum of squares and how you build that, which is a precursor for calculating the variance.
Good play: interactivity in R Markdown
So with good characters, we now had one pillar in place to help make our content feel a little bit more friendly. And the next step was to include good play. And by that I mean taking full advantage of the HTML output that you get with our markdown by inserting movement and interaction so that the learner actually has something that they can do on your site. And I just want to share five examples of packages and tools that we found most useful for this.
The first one is Plotly. So Plotly lets you create clickable and interactive plots so that a learner can see a concept play out in real time. This, for example, is a Plotly plot that we used to explain why the equation for sample variance needs to be divided by n minus 1, and we, of course, explained this in the text before showing this plot.
And another good thing that you can use for good play is the Gifsky package, which lets you make GIFs. And so once you've installed Gifsky, you can include an animation hook in the code chunk settings, and this will stitch together any plots that are output from that code chunk. So this GIF here was made by throwing several ggplots in one code chunk and then looping through all of them with something like either a per function or an apply function. But you can actually use the Gifsky hook to make GIFs out of regular images as well, so you're not just limited to ggplots. This is a GIF that we made to represent very abstractly the process of going from cross products to covariances and then standardizing those to become correlation scores.
But the most important part of good play that we wanted to give our learners was the ability to go through some stats methods by hand, or in other words, we wanted learners to have a chance to break apart functions, write their own functions, at least ones to kind of eliminate that statistical black box feeling, and in order to do that, we needed interactive console windows in our site.
So our solution was to take a LearnR window and embed it into our R Markdown website. Here's an example of how this works. So if you have not seen the LearnR package before, LearnR documents are R Markdown documents that can be used as interactive tutorials, and they usually exist as standalone things or standalone apps, but what's really cool about them is that they have these built-in little consoles, so you can preload code into them for a learner or text. You can also preload solutions, which a user can then run and see their output, and that's great.
So one of the problems, however, is that when a user is using a LearnR document in the iframe, it's a little tricky to get it to resize appropriately when the user is interacting with it, and so a solution to get it to resize appropriately is to use a little bit of JavaScript, and in particular something called an iframe resizer, which does exactly what it sounds like. So to our knowledge, this is the first time that someone's applied an iframe resizer to a LearnR window that's inside of an iframe, and the process for it is a little bit involved, so I'm not going to cover the details here, but I have created a step-by-step guide that shows you how to do this in your own R Markdown documents, and you can find that on my blog, which is at deseret.rbind.io.
And LearnR windows are not the only things that you can embed, of course. There are two more quick pieces of good play that I'd like to share with you that are considerably easier to embed in your site. So first there's a regular shiny app like this one, which we used to have learners guess correlation values, and using the same iframe approach, you can also embed quiz questions, and we haven't yet done this in our project, but we look forward to asking really tough quiz questions like this one.
So by using Plotly, Gifski, LearnR, and Shiny, we could make our R Markdown site so much more interactive, and there's still one more piece missing that I'd like to share, though, about our site, and that is good design.
Good design: layout and styling
And so by this I mean the page layout and styling that's distinct from the content, but brings good vibes and a sense of polish to your product. So essentially judging a book by its cover or by extension, judging a site by its HTML and CSS. And while this is, of course, not the best way to measure the quality of your content, the degree of styling that you give your site not only changes a learner's first impression when they first see your page, but it can also improve readability, navigation, and the user's general experience as they go through your content.
So out of the box, here is what our R Markdown site might have looked like just using the default settings for an R Markdown website. And this is a decent start, but I want to share three things that I think deliver some pretty big impact. And the first is decluttering.
So we do this by getting rid of borders and highlights and numbers that are not absolutely essential to our output. And then we can add a whole lot more white space so things don't feel so cramped. So around the table of contents, between paragraphs and headers. We can also constrain the width of the body of the text. And finally, we can increase font size and the line height of the paragraph, too. And so once we've made these changes, we get a lot more breathing room on the page and it's easier to read.
Most of these changes do involve a little bit of CSS, but if that scares you, one non-CSS thing that you can do in your R Markdown document, straight in the document itself, is just by adding backslashes or line breaks on their own lines. And adding that space in between is manually something that goes a long way when it comes to making more breathing room.
The second thing I want to share about good design is setting the visual ambiance for the site by adding a big image to the top, which in the lingo is called a hero image. And so you can do this if you're familiar with the R Markdown setting for the includes before body option, and you can just insert a file in there that references some big image to go at the very top of your page.
And finally, making use of built-in features of Pandoc, which is what runs under the hood of R Markdown, to make things like note boxes. So these can help organize your page content and help call out things like instructions or notes or critical thinking questions for your learners. Here we've used them to encase the learning objectives for this particular module. And the step-by-step process for making these note boxes is also something that you can find on my blog.
So there's some other things that you can tweak as well. Things like adding a logo, Google fonts, you can customize your nav bar. And these and many other good design elements I've shown you today are things that, again, involve some CSS. If your experience with CSS in the past has been either difficult or nonexistent, I hope that this does not stop you.
So this past summer I interned at RStudio with Allison Hill, and we started to create some R Markdown templates so that you can create these very same layouts in an out-of-the-box way. These two are still works in progress, but the resources called RStudio for EDU and RMD for EDU will be coming to a GitHub repository near you, so you can keep a lookout for those later this year.
Putting it all together
So now I've shown you some examples of good characters, good play, and good design. And I think it's worth mentioning that all of these things are things that Hass and I did without ever needing to leave the comfort of our favorite IDE.
And I think it's worth mentioning that all of these things are things that Hass and I did without ever needing to leave the comfort of our favorite IDE.
And with that, I can now show you what it looks like when you put all of these things together. If you'd like to check out the wonderful world of teacups, giraffes, and statistics, you can do that at bit.ly. For the best experience, I recommend doing that on desktop and in the Chrome browser. But the source code for all of this project is something that you can also get to by clicking on the GitHub logo and the nav bar of the site, and that will take you straight to the GitHub for it.
We're still in development for this project, and we're just starting to test this out with real live learners, but we welcome GitHub issues and blog comments or come find us at some point. We'd love to get your feedback and hear your questions about it. I hope this has given you some ideas for what's possible to make when you're teaching with our markdown, and we hope that you can incorporate some good characters, good play, and good design in your next project.
And so with that, I'd like to thank my co-author, Hass Olam, for being the other half of this project, Allison Hill for helping me package up so many of these designs and layouts in a way that I'll be able to share with all of you soon, and also Carl and the rest of the education team for their support of the giraffe project.
Q&A
First question, for people with no design background, do you have any recommended resources or starting points? Yeah, certainly. So the things that I've been developing with Allison Hill I think will be a great start for that, so that our studio for EDU, I mean, again, those things are still in development, but I think it's important to note, so when Hass and I started this project, neither of us had any knowledge of CSS. It mostly started off as, oh, we saw this really cool thing online, let's start Googling, is this possible to do with our markdown, and we didn't know the right search terms or anything like that. So I think if you have enough grit and perseverance, you can get anything that you see out there on the internet to work with our markdown, but the things I'm working on with Allison will hopefully make that process easier.
Okay, and the second one is, how are you going to tell whether this is actually helping people with the stats? Yeah, that's a great question, so that comes as soon as we start getting feedback from real learners. So we have Google Analytics up, which are helpful to some degree, but I think we need to pilot this out in real classrooms to see what the in-person learner thinks about it, and then from there we can think more creatively about how to get feedback from online learners.
Third question is, have you been thinking about taking this to the general public, the sort of audience that our previous speaker was talking about? Yeah, so I mean, I guess the idea is that we want to reach as many people as possible. That was part of the reason why we wanted to make this content feel as friendly and fun as we hope that it does. I mean, if we can make something appealing to people who have never even previously thought they'd be interested in stats, then we think that we can reach a lot of different communities and groups of people.
Okay, and last question before we break for lunch. You said that a lot of people looked at this and thought that you were actually writing a children's book instead. Have you thought about writing a children's book? I would love to write a children's book.
