The Carpentries is preparing to retire this handbook at the end of 2023. Existing content that has not already been replicated elsewhere will be relocated. See the relevant issue on the source repository for more details.

Chapter 8 Technological introductions

Our goal is to make developing and contributing to lessons as simple and accessible as possible. The more people who are able to contribute to a lesson, the more we can harness community knowledge and experience to create materials that are teachable and applicable in a range of learning contexts. We recognize that technology can be a major barrier to contribution, and we are currently working on a major update to our lesson infrastructure to reduce this barrier. This chapter reflects our current lesson infrastructure and describes what lesson authors and other contributors need to know to use The Carpentries lesson template. In the individual sections below, we have noted whether particular technological knowledge will remain necessary or be phased out in upcoming infrastructure updates.

What knowledge are we assuming lesson authors will have? What knowledge will this chapter help them gain?

8.1 Lesson hosting and rendering

The Carpentries hosts all of our lessons on GitHub. We use a shared lesson template to provide aesthetic and structural consistency across our lessons. Template files for each lesson are rendered into a webpage using Jekyll - a static site generator which is written in Ruby.

You do not need to know Ruby or Jekyll to write or contribute to a Carpentries lesson. However, you will need to have these software packages installed on your computer if you want to view your lesson materials locally before pushing them to GitHub.

Information about installing Ruby and Jekyll is available in the APPENDIX.

8.2 Using the lesson template

Each lesson is made up of episodes, which are focused on a particular topic and include time for both teaching and exercises. A lesson repository (or “repo”) includes one file for each episode, and a set of helper files that are required to build the lesson webpage. Most of these helper files are standardized across all of our lessons and aren’t something that lesson authors or contributors need to interact with. In this section, we will focus only on the files that you are likely to interact with. If you’re interested in the details of how the template is structured, and what each of the files does, these details are provided in APPENDIX. We recommend not spending time learning these details now, as we are in the process of greatly simplifying our lesson template.

8.2.1 Creating your lesson repository

The following sections will guide you through the pieces of the lesson template that you will need to modify to create your lesson. In order to follow along with these examples, you can start by creating your lesson repository in GitHub. To do this, follow the setup instructions on our example lesson.

8.2.2 Lesson homepage

The lesson homepage provides an overview of the lesson, including any prequisites, an introduction to the dataset used, a schedule showing the episodes and the time alloted for each, and any other information learners will need for the lesson.

For inspiration to guide you in writing your lesson homepage, check out these examples for Data Carpentry, Software Carpentry, and Library Carpentry.

The lesson homepage is built from the index.md file, which is automatically created when you initialize a lesson repository. You will need to add the following to this file:

A few paragraphs of explanatory text describing the lesson.
One or more .prereq boxes detailing the lesson’s prerequisites, giving an overview of the dataset, and/or calling attention to the lesson’s Instructor notes.

The schedule will automatically be included in the lesson homepage based on information present in the episode files.

8.2.3 Episode files

The majority of a lessons content is in its episode files. Episode files are stored in the _episodes/ folder within your lesson repo (or in _episodes_rmd/ for lessons written in R). Episode file names must start with a two-digit identifier number (e.g. 01) followed by a short descriptive name, separated by a dash (-). For example 02-loop.md, 03-lists.md. The numeric identifier is used to place your episode files in the correct sequence within the lesson. Episode files are written in Markdown (more on that in a moment) or RMarkdown.

8.2.3.1 Episode headers

When your lesson repository is created, it will start out with one pre-made episode file (01-introduction.md). You can use this file as a template for creating each of your episode files, as it provides an example of how these files must be structured. The content of this pre-made episode file is shown below:

---
title: "Introduction"
teaching: 0
exercises: 0
questions:
- "Key question (FIXME)"
objectives:
- "First learning objective. (FIXME)"
keypoints:
- "First key point. Brief Answer to questions. (FIXME)"
---
FIXME

{% include links.md %}

The material between the first and second instances of --- is called the YAML header. The information stored in the YAML header is used by the lesson template to populate important parts of the lesson webpage. This section explains each component of the YAML header and what that information is used for.

For each episode, you will need to create a copy of this file and:

Replace Introduction with the episode title (not the lesson title) in quotation marks. The episode title will appear on the episode page and in the schedule that appears on the lesson homepage.
Enter an estimated number of minutes for teaching the episode and an estimated number of minutes for learners to spend completing challenge problems (including class discussion of challenge solutions). These time estimates will likely be updated by Instructors as they get real-world data on how learners respond to the pacing of the episodes, but it is useful to have a starting point to benchmark from. The lesson template creates a schedule from these time estimates and places it on the lesson homepage.
Replace Key question (FIXME) with 1-3 motivating questions for the episode, each on a new line and in quotation marks. These motivating questions will appear in the schedule on the lesson homepage.
Replace First learning objective. (FIXME) with 3-7 learning objectives for the episode, each on a new line and in quotation marks. For information on writing useful learning objectives, see the Developing Content chapter.
Replace First key point. Brief Answer to questions. (FIXME) with 3-7 major take-aways from the episode. For information on how to distill an episode’s key points, see the Developing Content chapter. Key points for all episodes are shown together in the lesson’s reference page.

8.2.3.2 Episode content

After the YAML header, your episode file will contain the content for that episode. This content will likely include:

paragraphs of text
lists
tables
images or figures
code chunks
special blockquotes, including exercises and solutions (described below)

This content will be written in Markdown, a light-weight markup language that makes it possible to create fancy HTML pages using only a few formating tricks. In this section, we’ll cover only the Markdown syntax that you will need in order to create the content types listed above. You can find more information about Markdown at https://commonmark.org/help/.

Paragraphs of text - To create text paragraphs in Markdown, just type as you normally would! A few neat tricks:

surround text with a single pair of stars (*) to make text italic (*italic*)
use a double pair of stars to make text bold (**bold**)
create headers by starting a line of text with two hash signs (##) There are lots of other fancy things you can do, but this should get you started!

Lists - To create a numbered list in Markdown, do this:

1. A
1. numbered
1. list

This will show up like this:

A
numbered
list

Hint: You can use sequential numbers if you want, but it’s easier to update the list later if you use only 1s. Markdown will create the sequence for you.

To create an un-numbered list in Markdown, do this:

* An
* unnumbered
* list

This will show up like this:

An
unnumbered
list

Tables - To insert a small table into your episode, do this:

| Category | Item |
|--------- | ---- |
| Food     | Sandwich |
| Drink    | Tea |
| Food     | Apple |

This will show up like this:

Category	Item
Food	Sandwich
Drink	Tea
Food	Apple

Images or figures - Place a copy of the image you would like to display into the fig directory. You can then link to the figure using the syntax:

![Figure Description](../fig/figure_file_name.svg)

Note about alt text. Question: Is this the “proper” way to insert a figure link?

Code chunks - As discussed in an earlier chapter, Carpentries workshops are taught using participatory live coding. Instructors type the code as they teach it and learners type along with the Instructor. For more information about how live coding works, and what its advantages and disadvantages are, read that section of our Instructor Training program. The fact that Carpentries workshops are taught using live coding means that much of your episode content will be code chunks - short blocks of code that learners type along with the Instructor and evaluate on their own machines. Each code chunk should correspond to one interactive session. If learners will be running the code as two distinct commands, that code should be displayed as two distinct chunks in the episode file.

You can add a code chunk to your episode using the following syntax:

~~~
pwd
~~~
{: .source}

Which will show up like:

pwd

Code chunks that learners should type out with the Instructor should use the {: .source} tag as shown above. Chunks that show expected output should use the {: .output} tag. Chunks that show an expected error message should use the {: .error} tag.

The generic {: .source} tag can be used for all programming languages. To make your code more stylish, you can use a language-specific tag (instead of {: .source}). This will add things like syntax highlighting to your code. The language-specific tags available with our lesson template are:

{: .language-bash}
{: .html}
{: .language-make}
{: .language-matlab}
{: .language-python}
{: .language-r}
{: .language-sql}

You don’t need to use these language-specific tags, but they make your lesson a little prettier.

Special blockquotes - Exercises, solutions, helpful tips, and a few other types of special information are formatted as blockquotes within the episode file. Each blockquote has the same general structure, but ends with a different tag. The ending tag determines how the blockquote will appear on the lesson webpage. The general structure of a blockquote is:

> ## Title
>
> text
> text
> text
{: .callout}

where the {: .callout} tag should be replaced with one of the following as appropriate:

{: .callout} for sharing an aside or comment. Use sparingly.
{: .challenge} for an exercise.
{: .discussion} for a discussion question.
{: .solution} for an exercise solution.

Additional blockquote tags included in our lesson template are described in APPENDIX, however, the four listed above should cover all normal use cases for a lesson author.

Exercise solutions are nested within the blockquote for that exercise, as shown below:

> ## Challenge Title
>
> This is the body of the challenge.
>
> > ## Solution
> >
> > This is the body of the solution.
> {: .solution}
{: .challenge}

Code chunks may also be nested within blockquotes as needed.

8.2.4 Extras

So far we’ve covered how to create and format the content of your lesson homepage (in the index.md file) and your lesson episodes (in multiple .md files within the _episodes directory). This covers most of the files you will need to work with when you create a new lesson. There are a few remaining files that you will need to populate in order for your lesson to be fully fleshed out and ready to teach:

The Reference page (reference.md) - this file will be created automatically and will include a list of all of the keypoints that you defined in your episode YAML headers. You don’t need to do anything to create this list! However, it’s a good idea to add a glossary of terms that are used in your lesson.
The Setup page (setup.md) - this file will be created automatically, but needs to be populated with installation instructions for software learners will need to have before begining the lesson. If learners are expected to download data prior to the workshop, that data should also be linked and described here. The setup page may be quite simple or more complex, but should always include installation information for all three major platforms (Windows, Unix/MacOS, Linux).
The Instructors’ Guide (_extras/guide.md) - this file should provide additional discussion useful to instructors, but not appropriate for inclusion in the main lessons. Remember not to overload on details, and to keep the information here positive and useful for instructors! This guide should include the following sections:

Lesson motivation and learning objectives - These concepts should be highlighted in the main lesson material, but ideas for explaining these concepts further can be placed here.
Lesson design - Most lessons contain more material than can be taught in a single workshop. Describe a general narrative (with time estimates) for teaching either a half day or full day with this lesson material. You may also choose to include multiple options for lesson design, or what material can be skipped while teaching. This section may also include recommendations for how this lesson fits into the overall workshop.
Technical tips and tricks - Provide information on setting up your environment for learners to view your live coding (increasing text size, changing text color, etc), as well as general recommendations for working with coding tools to best suit the learning environment.
Common problems - This can include answers to common learner questions, as well as links to resources (blog posts, stack overflow answers, etc) that may solve problems that may occur during a workshop.

8.2.5 Other information

In addition to populating the lesson homepage, lesson content (episodes), Instructors’ guide, and other lesson-specific pages, lesson authors need to make a few changes to the template files to make sure that the lesson has all of the neccessary information.

In the _config.yml file,

set the carpentry variable to the appropriate lesson program,
set title to be the overall title for your lesson,
set email to the correct contact email for your lesson.

In the CONTRIBUTING.md file, change the issues and repo links to match the URLs of your lesson.
In the CITATION file, add information about how to cite your lesson.
The AUTHORS file should include a list of the lesson’s authors.

8.2.6 Special notes on RMarkdown

It is also possible to write episodes in RMarkdown, to be executed and rendered as pages via an automated step in the lesson template configuration.

To learn more about how to incorporate RMarkdown documents as episodes in a lesson, please read the Using RMarkdown section of The Carpentries Lesson Example. The Lesson Example page assumes the reader is already familiar with the Rmarkdown framework. For those wishing to get started with writing in RMarkdown, this online book provides an excellent introduction.

8.3 Working on GitHub

GitHub is a web-based service for hosting code under version control. In addition to being a technical platform, GitHub is also a social media platform and has its own standards around etiquite and interaction. This section describes how The Carpentries community tends to interact on GitHub and gives you some tips for navigating this new social scene.

All Carpentries lesson materials, whether they are established or in early development, are hosted publically on GitHub in one of several organisations. The following high-level organisations are managed by The Carpentries:

carpentries - hosts The Carpentries website and materials for programs that span individual lesson programs, such as our Instructor Training curriculum and The Carpentries Handbook
datacarpentry - hosts Data Carpentry specific lesson materials and website
librarycarpentry - hosts Library Carpentry specific lesson materials and website
swcarpentry - hosts Software Carpentry specific lesson materials and website
data-lessons - hosts lessons in development which are targeted to become part of the official Carpentries lesson stack
carpentrieslab - community-developed lessons which may or may not become part of the official Carpentries lesson stack

In order to contribute to lesson materials, you will need a GitHub account.

To manage changes, we follow GitHub flow. Each lesson has two maintainers who review issues and pull requests or encourage others to do so. The maintainers are community volunteers and have final say over what gets merged into the lesson. To use the web interface for contributing to a lesson:

Fork the originating repository to your GitHub account.
Within your version of the forked repository, move to the default branch (e.g. gh-pages) and create a new branch for each significant change being made.
Navigate to the file(s) you wish to change within the new branches and make revisions as required.
Commit all changed files within the appropriate branches.
Create individual pull requests from each of your changed branches to the gh-pages branch within the originating repository.
If you receive feedback, make changes using your issue-specific branches of the forked repository and the pull requests will update automatically.
Repeat as needed until all feedback has been addressed.

When starting work, please make sure your clone of the originating gh-pages branch is up-to-date before creating your own revision-specific branch(es) from there. Additionally, please only work from your newly-created branch(es) and not your clone of the originating gh-pages branch. Lastly, published copies of all the lessons are available in the gh-pages branch of the originating repository for reference while revising.

If you choose to contribute via GitHub, you may want to look at How to Contribute to an Open Source Project on GitHub.