Design principles for the next iteration of The Carpentries lesson template

This blog post introduces twelve design principles that will guide the development of the next version of The Carpentries lesson template. First, we provide some background and definitions. If you are more interested in the principles themselves, you can skip forward to the Design Principles section.

Background

In The Carpentries’ history (including Data Carpentry, Library Carpentry, and Software Carpentry), we have learned a lot about lesson templates. We have had two main versions of the template that relied on GitHub Pages. As the community grows, we are adding more lessons through [our community-developed lessons]({{ site.url }}/community-lessons/) (The Carpentries Incubator and The Carpentries Lab) every week; and we are starting to see the limitations of our current workflow. Given changes in the tools and infrastructure, we are envisioning the next iteration of the lesson template.

The next iteration of the lesson template needs to be accessible, inclusive, and intuitive. We want this to be true for all its users, within and beyond The Carpentries.

Anatomy of a lesson workflow

Drawing of the components that lead to rendered lesson. A rendered lesson is the output by a rendering tool of a lesson template and the lesson content

Our lesson template workflow consists of four main parts: the rendered lesson, lesson content, styling elements, and rendering tool. All of these components are open source and accept contributions from all members of our community. Since we will be using these terms thoroughout the blog post, we should define them here (arranged in order of visiblity to a learner):

Rendered lesson is the output (typically a website) that learners and instructors use.
Lesson content is the actual content of the lesson. It is a series of episode files (typically written in Markdown or RMarkdown) and a few other files (images, datasets) that together compose what the instructor uses to teach and the learners to learn.
Styling elements is a group of files that control the styling of the final output. It is formed by a combination of CSS, JavaScript, and HTML templates.
Rendering tool is the software that combines the lesson content and the styling elements to generate the rendered lesson. There are two main categories of tools to do this. Some rely on having a server-side system that generates the pages on demand for the users of the website. Other tools are static site generators, the rendering tool generates all the pages in advance. In The Carpentries, we have been relying on Jekyll (a static site generator) because it is what GitHub Pages uses, and not having a server to manage to render our lessons is easier. With a static site generator, it is also easier to work with the lessons without an Internet connection.

Who uses the template?

There are six types of users for the lesson template (arranged by level of interaction with the template):

Learners use the rendered lesson to gain knowledge about the subject material.
Instructors teach the lessons. They need the rendered lesson to provide clear content they can use to guide their instruction. They are also required to contribute a small improvement to lesson content as part of the instructor training checkout process.
Lesson contributors — In The Carpentries, we use an open-source model of lesson development. Lesson contributors detect something that can improved in the rendered lesson, and need to find what to change in the lesson content to make this improvement.
Lesson maintainers are responsible for triaging contributions to the lesson content. They need to ensure that the contributions they merge are valid (i.e., they follow the syntax expected by the template and the rendering tool). They also need to be able to preview the rendered lesson before the proposed changes are merged upstream.
Lesson creators are the original authors of the lesson. Similarly to lesson maintainers, they want to focus on the lesson content rather than the tooling that will generate the rendered lesson.
Template contributors want to address bugs and improve the styling elements of the template. They should quickly find the files they need to edit to suggest their changes, and easily generate a rendered lesson to test the impact of their suggested changes.

The tooling, template, and syntax should support the needs of all of these users.

Pain points with the current template

Our lesson template was initially designed in an era when the simplest way to deploy a markdown-based website was through GitHub Pages, which uses — and continues to use — the Jekyll static site generator. This model has supported over 20 official lessons, as well as many lessons that are not part of our official offerings. It has even been adapted for non-Carpentries materials. However, the template has shown itself to be a bit of a Norman door in the following ways:

Previewing the site locally requires people to have or install Git, Make, Python, Ruby, and Bundler. If they want to develop lessons for R, then they need R installed as well. Installing these elements takes a lot of time and debugging effort that would otherwise be spent on the lesson content.
File organisation was not intuitive, especially when using rendered lessons via RMarkdown.
By bundling the styling elements (boilerplate HTML, JavaScript, and CSS) in the repository, lessons rapidly become outdated and difficult to update as it requires advanced Git knowledge to resolve any conflicting changes.
While Jekyll can generate sites that work offline, creating a template that support both online and offline output is tedious and error-prone.

All of these issues are accessibility and inclusion issues. Our volunteers’ time is precious and lesson authors, contributors, and maintainers should only need to focus on the lesson content instead of debugging a parsing error due to incompatibilities across versions of Jekyll. The styling elements and the rendering tools need to “just work” for our community and we have identified twelve principles that will help us achieve this goal.