Zhian N. Kamvar | Building Accessible Lessons with R and Friends | RStudio (2022)
The Carpentries is a global community of volunteers who collaboratively develop and deliver lessons to build capacity in data and coding skills to researchers worldwide. In the recent redesign of our lesson infrastructure (serving more than100 lessons, used daily by more than 5K learners), we replaced embedded Jekyll templates with a workbench of modular and accessible packages using R and Pandoc. By leveraging renv and knitr for R-based lessons, we provide a seamless and collaborative lesson development experience that maximizes reproducibility and minimizes frustration so authors can focus on the contents, not the tooling. We demonstrate how anyone can use our infrastructure to build customised and accessible sites for their own lessons or tutorials. Talk materials are available at https://github.com/zkamvar/rstudio-conf-2022 Session: It takes a village: building communities of practice
image: thumbnail.jpg
Transcript#
This transcript was generated automatically and may contain errors.
I'm going to tell you two things in this talk. First, how you can build accessible lessons with the Carpentries Workbench. And second, how we used R to build the Carpentries Workbench, which allowed us to transform our lessons from looking like this to looking something a bit more like this.
And I have a lot of people that I need to thank for this talk, including the RStudio Diversity Scholars Program, which brought myself and soon-to-be Dr. Sharon Hurt to this conference, but I don't really have the time to go over this. And what you need to know about this talk is that you need to know who the Carpentries are in order to appreciate it.
Who the Carpentries are
In order to understand who the Carpentries are, I'm going to tell you a little story about myself. This is not a recent photo. This was from 2014. I was teaching my very first conference workshop in Population Genetics in R, giving it to plant pathologists. If you're wondering what Population Genetics in R is, think 23andMe, but for fungi.
So in this workshop, I wrote the materials all in R Markdown. I forced my advisor to use Git and ended up fixing a lot of merge conflicts, and the process of building this was very painful. It was very much close your eyes and hope it works. I did end up building the website, but that version of me knew quite a lot about Population Genetics, knew quite a lot about plant pathology, didn't know very much about inclusive teaching, custom design, or live coding, and this workshop, it was actually successful.
We ran it for two years, got really good reviews. People liked it, but something was really bothering me. Something was eating me on the inside. I didn't actually know what people learned. I knew they learned something. They had their computers open. They were following along, but I don't know what they learned, and here's the thing. My advisor had no way of supporting me in that. He was a government scientist.
He hadn't taught a course in years, and so if I had a way to get the support I needed, such as maybe a template that could have given me the narrative elements and elements for formative assessment, I would have been able to succeed in understanding what my learners learned and then improve that lesson over time, and I know now that the Carpentries provides that support and gives a safe space for improving my teaching, and the Carpentries is all about spreading data science skills to researchers around the globe to really democratize access to data.
And it does this by fostering communities of practice, and these are volunteers who are trained in evidence-based teaching principles from all around the world, and we all come together through shared core values in that we are motivated in that we are always learning and we're inclusive of all. In practice, we act openly. We empower one another, and we value all contributions, which allows us to achieve our goals of championing people first, access for all, community collaboration, and strength through diversity.
And we know that it works because we have led over 3,500 workshops in the past 10 years to over 60 countries, 3,900 instructors, 45 lessons to over 80,000 novice learners in over 90 member institutions. So it's a lot of number, but the key to this, the reason why this works is because our instructors never teach alone.
In a Carpentries workshop, if you are an instructor, if you're a new instructor, you're always paired with someone who's taught this before, and this is always possible because of the efforts of our director of workshops, Sharon Hurt, who allows you, who gives you the opportunity to teach these workshops, and these workshops would not be possible without our open source and open license materials that are available on GitHub, and it's these materials that I'm going to talk about for the rest of the talk because these have a long history.
They were originally written in HTML, just straight HTML. Really difficult to write if you're not, if you're really tired or, yeah. Eventually they switched over to Jekyll, which is GitHub's default site generator, and I'm going to ask for a little audience participation here, okay?
So I'm going to ask you three questions. If the answer is yes, I want you to clap twice, okay? With me? So first question, just to get a baseline, if you have ever used Jekyll, clap twice. Okay, good. If you have ever uttered a curse word while using Jekyll, clap twice. That was about the same, okay. If you have ever wanted to set your laptop on fire while using Jekyll, please, clap twice. Okay.
So yeah, Jekyll's kind of hard to use, and the thing is, it's been shown as a barrier. When you're just trying to build a lesson, when you're trying to work on a lesson, you just want to fix a typo, you want to update an image, and you find this, you really want to burn it all down. It's not easy to use, and the thing is, it wasn't living up to our values. This really did not put people first. This was putting the machines first.
Building the Carpentries Workbench
And so I was hired in 2020 to reimagine this infrastructure, because it was clear it was not living up to our values. And what I realized is that we really need to separate the tools from the content. Anything everybody should worry about is just being able to write markdown, or R markdown, and get a website out of it, and not having to sift through all the output that's contained in the same folder, or having to worry about tools breaking.
And so this is how I created the Carpentries Workbench, and this is a series of packages that avoids having a lesson being wrapped around a blog infrastructure, and it keeps the tools and outputs separate, and it's based on the philosophy of package down. Work where you are.
And this, it consists of three packages. The first package that you're going to interact with is sandpaper. This is what orchestrates everything. The only command you really need to know is sandpaper serve. The next package is on the inside, and you don't interact with it so often, but you do with it, you do, sandpaper uses it in the backend to help you validate your markdown, to make sure that it actually is going to do what you want it to do. And then coming in at the end is varnish. That gives you the styling of your lessons, to make sure that your lessons are accessible and beautiful.
And all of this was designed with what I like to call core values-driven design. And so I'm going to talk about a few of our core values and how the design elements fit in with them. There are a lot more, but I don't have that much time.
Core values-driven design
So the first thing I'm going to start with is championing people first, because really individuals who make up our community are the most important part of our organization. And they are our strongest resource. So it only makes sense that when I was looking for a static site generator, something to generate our websites with, that I would choose something that had the most on ramps. And really, R is the best resource. It makes the most sense.
You saw it in Ileana's talk, and you see it here. And this tweet from Janita Bellini, and she says that some people laugh when I tell them that R's best feature as a language is its community, but I'm very serious. Especially Rladies has been such a positive agent of change for so many people. That's one of the reasons why y'all are here. We are a good community here. We know how to make people feel included. And so it only makes sense.
And this tweet from Janita Bellini, and she says that some people laugh when I tell them that R's best feature as a language is its community, but I'm very serious.
Another way that we're championing people first is that we virtually increase the number of instructors in the room when you're teaching a lesson. And I'm going to explain what I mean by that. So you have your lesson. It has code examples. And you want to teach someone how to add a column to a data frame. Okay? So you are working in RStudio, and you show them the code, you run the code, and then you have output that looks like this. You can't really tell what happened, because there are so many columns in the data frame, everything ran off the edge.
If you had the wisdom of the instructors who came before you, and yes, you are teaching with another instructor. They may know this, but they may not. You would know that you have to add a select command. And so what we do is we allow instructors to communicate through time and space by allowing them to include instructor notes directly into the lessons in the context that is needed. So that when you teach this lesson, you can change your behavior, and you can show the learners what exactly they need to know and reduce their cognitive load.
And another way we champion people first is that we include automation. Oftentimes, as you're building R Markdown, packages will update. Things fail. You get a lot of errors. You get warnings that don't make sense, because the package authors changed their packages. We avoid this by embedding renv on the back end of sandpaper. And the beauty about this, you don't need to know anything about renv in order to use this. We lock the packages. We give you a way to update them, and we give you a way to pin them so that your lessons are always working and you have a way to investigate what happens when packages update. And I'm going to show you some of that a little bit later.
And really, this leads me into the fact that we champion access for all, because it shouldn't matter what packages you have on your system. It shouldn't matter what packages you have in your global library. You should be able to build the lesson the same anyone else can build the lesson. And so I'm going to show you, like, what happens when you don't have your own computer, when you're not on your own computer and you receive a pull request. That changes a plot. But can anybody tell me what's going to happen when this happens? Probably not. Because it's R code. But seeing the output of the plot is night and day.
And we have embedded pull request previews for the intermediate markdown for these lessons so that you can confirm that things actually work, whether or not you have the tools installed.
And furthermore, if you're writing an R lesson, sometimes you may forget to include alternative text or you have link descriptions that don't actually describe anything. And you say, whoops. And it's this kind of preflight validation that's done by Pegboard that allows you to take a step back and say, yeah, I made a mistake, and fix it. And that's really the key to how we're championing access for all, and we're always learning. Because we're humans. We forget things. You shouldn't be punished. You shouldn't have, like, glaring errors when you miss something. When you mistype something. And it shows that we're always learning.
And I'm going to turn it on myself. I'm always learning. Sandpaper is not the fastest thing in the world. The Workbench is not the fastest thing in the world. But I really want to address the pink pachyderm in the premises. We don't use Quarto yet. Sorry. But the way I designed the system, we're going to include Quarto in the future. We just need to get it stable in our system. And I built it to be flexible. So it works on the exact same principle that Quarto works.
And then finally, I want to get to the fact that we empower one another. The Workbench is going to support 168 lessons come January. And this is really key, because most of these lessons are in the Carpentries Incubator, in which people are actively developing lessons, working on lessons, testing them out, teaching them, and getting feedback and revamping them in this iterative development cycle that eventually leads to peer review of lessons. And this is the Carpentries Workbench makes this model sustainable. It makes it much easier for people to do these iterations with all of these safeguards that we've built into it.
Community voices
And so it's here that I want to show you that I'm not the only one who thinks this. I'm not the only one who claims this. Saba Ferdas from UCL, she's part of the Learn to Discover project. She forked sandpaper and made it run Python. And she says that it was very trivial and efficient to write custom lessons with the Carpentries Workbench. I have a link there. My slides are online. I'll give you a QR code for that.
Toby Hodges, he's the curriculum lead of the Carpentries. He works with the community, and he says the Carpentries Workbench has made it easier for people to write, maintain, and teach lessons in many different ways, sometimes quite profoundly. Sarah Stevens, very embedded in the Carpentries, and she says, I'm really excited to be able to use the Workbench's accessibility features, because she's tired of not having reminders to add alt text. And finally, Francois Michonneau has been working with the Workbench since the beginning, and he says you only have to focus on writing content, and the Workbench takes care of the rest.
And he says you only have to focus on writing content, and the Workbench takes care of the rest.
Getting involved
And so here's a link that you can use, and you can create your own lesson using the Workbench. And now you can build your own accessible lesson using R. But that's not what the talk title is, y'all. Okay? What about friends, huh? This is Building Accessible Lessons with R and Friends, and this is where I put in a plug for the Carpentries. I want y'all to get involved, because really, we are a great community.
There are plenty of ways to be involved in the Carpentries, and it's really a community of practice. You get so many opportunities to interact with people who really care about teaching. You can become an instructor. Next summer, we're going to open up applications for maintenance of our lessons. You can teach, create, contribute to, or review a lesson, or even just take our materials. They're completely open. Or if you're part of an organization, you can have that organization enroll as a member and use that to build your own community in your organization.
And if you want to know more, we have a conference that's happening right after this conference. It's online, and we have an accessibility fund, if you want to donate to it, to make sure that we have money for translators, money for people who do captioning. And it's free to attend, so if you want to learn more, please attend. I have my slides. I have information about the Workbench, and I'd be happy to take any questions if I have time. Okay. Thank you.
