Introducing The Carpentries Workbench

What is The Carpentries Workbench?

The Carpentries Workbench is a fresh redesign of our lesson infrastructure¹ from the ground up that clearly separates the tools from the content. We hope it will better serve the needs of our community members and create paths forward for improving access, portability, stability, and reliability of our lesson infrastructure as the repertoir of our lesson developers continues to grow.

Following the guidelines we set out in our post on design principles, The Carpentries Workbench is built with R and Pandoc in three custom packages called {sandpaper}, {varnish}, and {pegboard} for deployment, styling, and validation, respectively. It is important to note here that knowledge of R or pandoc is not necessary to build a lesson using The Workbench. The only requirement is a working knowledge of markdown syntax. To find out more about the process we used for validating the usability of the infrastructure, you can read our blog post about the alpha testing and our blog post about the UX testing and design, or if you have 20 minutes to spare, you can watch a video of Zhian’s UseR!2021 talk: “Using R as Community Workbench for The Carpentries Lesson Infrastructure (with slides available here).

Because these are large changes with far-reaching consequences for our community, we are going to make this transition as smooth as possible, starting with a soft beta release in April 2022 with interested Maintainers, Lesson Authors, and Instructors. If you would like to begin exploring The Carpentries Workbench and help us out with beta testing, please get in touch by emailing me at zkamvar [at] carpentries.org. It is vital that we include a wide range of perspectives in this process. We would like to learn from your experience with the new infrastructure however you work with our lesson sites: whether that is teaching the lesson in a workshop, developing a new lesson, or maintaining an existing repository. Similarly, we are keen to include you regardless of your familiarity with the infrastructure on which our lessons are currently based: regardless of whether you are new to The Carpentries community or have been working with our lesson sites for many years, we want you to get involved.

Table of Contents

• Show me!
  • For Instructors: Instructor View
  • For Maintainers: Getting the Latest Features
  • And More!
• Transition Plan
• Future Plans

Show me!

You can see The Carpentries Workbench in action at the documentation site. Of course, pictures are worth a thousand words. I have converted the “Programming With Python” Software Carpentry Lesson and hosted it in a sandbox github organisation². This is what the ‘Making Choices’ episode of the “Programming with Python” lesson looks like right now using the Styles template:

In this example repository, I show what it will look like when we implement The Carpentries Workbench:

Callout blocks are getting a makeover as well. Compare two callout blocks from the introductory episode of the lesson:

For a full list of features in the episodes, you can visit the Episode Structure episode in the Carpentries Workbench documentation.

For Instructors: Instructor View

One resource that is useful for Instructors teaching new-to-them lessons is the Instructor notes, but this page is often buried in the “extras” dropdown menu. Because it is out of sight, it is not used often, and goes out of sync with the content of the lesson. And while it is useful to have an overview of all the tips to teach a lesson, the new infrastructure offers a way to include these in context in the lesson with the new Instructor View.

First, visit https://carpentries.github.io/sandpaper-docs/episodes#instructor-notes and you will see a section that contains a heading, paragraph, and a discussion block (in yellow).

Now, visit https://carpentries.github.io/sandpaper-docs/instructor/episodes#instructor-notes and you will find an Instructor note revealed:

Once we have the infrastructure established, we hope to organise Instructor note sprints for our Instructors to share their knowledge and contribute to the lesson development and maintenance.

For Maintainers: Getting the Latest Features!

Our current lesson template can be thought of as an all-in-one box of tools that you can add markdown files to and get a lesson out of at the end. One of the biggest pain points of this setup is that as the template improves, older lessons rapidly become outdated and miss out on new features. The official way to update a lesson with the new features is to manually create a pull request from the styles repository, but this can lead to a backlog of github notifications:

With the new lesson infrastructure, changes to the styling, even major changes are applied immediately. Take for example this chapter on editing (captured on 2022-01-28) and compare it with the same content, but using the previous version of the lesson infrastructure. This change happened with the click of a button (or had I been patient, I could have just waited a week for the change to implement itself).

And More!!!

There are many more features that should make authoring, contributing, and maintaining lessons easier for everyone including automated checks for missing alt text, abnormal heading structure, and invalid internal links.

We are now piloting the inclusion of BioSchemas metadata in our lessons so that they can be indexed and aggregated on repositories such as ELIXIR’s Training Portal, TeSS, which will increase the lessons’ reach and give more exposure to the work of our Lesson Authors and Maintainers.

One of the things we’re really excited about with the lesson infrastructure is a less invasive and faster build process for our R-based lessons that freezes the package versions and provides pull request previews that will avoid lessons suddenly breaking when new package versions are released.

Transition Plan

As mentioned earlier, we will not make this transition all at once. There are over a hundred lessons across The Carpentries (including Lab and Incubator), each with their own unique setup. Before any transition will happen, we will do one more lesson release and then slowly migrate the lessons based on an opt-in process by the Maintainers. Instructors will be notified at least two weeks in advance of these migrations.

For the Maintainers, we have set up a workflow for automated conversion with customisation, and once the Maintainers/Authors of the lesson are ready and they consent, we will transition the lesson, preserving the commit history (stripping the styles- specific commits).

Future Plans

The Carpentries Workbench is the first step towards making our lesson infrastructure more equitable and accessible, but we are far from finished. In the future, we can envision a lesson infrastructure that drives lesson developers towards the pit of success in terms of creating accessible and up-to-date lessons in any language (both human and computer). As we get closer to the official release of The Carpentries Workbench, we will reform and restart The Lesson Infrastructure Committee, which will serve as an advisory board for the project, as outlined in our blog post from December 2021.

How you can help

• If you are interested in beta testing The Carpentries Workbench and providing valuable feedback as we iterate on the infrastructure, please contact zkamvar [at] carpentries.org
• If you find any errors in the infrastructure, please consider opening an issue on the {sandpaper} repository
• Please continue providing feedback on the work outlined above

Thank you to our community who has been instrumental in calling for these changes, and in advance for helping The Carpentries as we transition to a more equitable and accessible lesson infrastructure. Thank you also to CZI Science for their support and funding for this work.