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):
There are six types of users for the lesson template (arranged by level of interaction with the template):
The tooling, template, and syntax should support the needs of all of these users.
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:
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.
Use best practices to ensure accessibility of the rendered lesson
In the USA, 1 in 4 adults has a disability. By using best practices for accessibility and compatibility with assistive technologies, the content of the rendered lesson should be accessible to most people.
Provide support for translations, multi-language content, and non-Latin characters
English dominates documentation and tutorials. This prevents many people across the globe from having access to technical skills. By providing support for translation and multi-language content, we want to equip lesson creators with the tools they need to write lessons in the language of their choice.
The rendered lesson can be used offline and exported in multiple formats
Internet access is still limited in most places. Providing a portable way to distribute the rendered lessons ensures that people with no or slow internet access can still have access to knowledge.
Lesson contributors should not have to worry about infrastructure
Occasional contributors to lessons should not have to worry about the tools that are being used to render the lesson. These contributors should focus on improving the content of the lesson and they should be able to quickly and painlessly have access to the rendered lesson that includes their changes.
Files should be organised in an intuitive way
The files that compose the lesson should be organised in the repository in a way that is clear and intuitive. From a glance at the repository, a contributor should identify what each file is doing and how modifying them will impact the rendered lesson.
The styling elements should not live in the lesson repository
The lesson repository should only contain information that is relevant for the lesson. The files that are needed to render the lesson website should not live within this repository.
Upgrades to the styling elements should be seamless
Having a clear separation of the lesson content and the styling elements makes it easy to bring continuous improvements to the template. If new features are being added or others are removed, there should be clear mechanisms and pathways to add or remove these features.
Issues with formatting of lesson content should be detected early and error messages should be informative
The lesson content should be parsed and any formatting issue should be reported before the rendered lesson gets built. Reporting on these issues should be clear, and solutions to solve them should be presented.
YAML header is for metadata
When writing Markdown files, a YAML header is useful to place structured information that is programmatically accessible for re-use within or across lesson episodes. However, the YAML header should only be used for metadata that are intended to be used by computers. If the primary target of the information is for humans, it should live somewhere else than the YAML header. More generally, people should not have to enter YAML by hand.
Dependencies are clear and easy to install for everyone
Whether you are a learner or a contributor to the lesson, the software you need to install to follow along or render the lesson locally should be clearly identified.
Instructor notes should be easy to access
Providing instructor notes for lessons is useful to help instructors explain the order in which concepts are being taught, ideas to emphasise when teaching, or common misconceptions that learners may face. Having these notes displayed in the context of the lesson (e.g., as asides) would guide instructors when preparing or teaching the lessons.
Components of the lessons can be exported for re-use and alternative uses
Instructors often need to extract components of the lesson to present them to the learners in different contexts. It should be easy to extract the figures, the exercises, the outline, the callouts, or the code chunks and automatically create slideshows and other outputs.
These design principles have emerged from numerous conversations with past and current lesson maintainers, the Lesson Infrastructure Committee, conversations with community members, and contributors to our current lesson template.
These design principles might evolve as we continue to work on this project. We will soon do a more formal call, but if you are interested in shaping this next iteration of The Carpentries lesson template, do not hesitate to send us an email at firstname.lastname@example.org.