Instructor Notes


The curriculum was piloted in six half-days, with an extended break for lesson trial runs between half-days 4 & 5.

Training Themes

Lesson Development as a Learning Process

A recurring theme in this training is the discussion of the benefits of piloting a new lesson and treating teaching as an opportunity to learn and improve the lesson. We have found it helpful to frame the discussion this way and to draw on our own experience when talking about the ways in which piloting a lesson can help to improve it. For example, when teaching the assessments or narrative section you might discuss a time when you piloted a workshop and realized there was a concept missing in the demo/narrative that learners needed in order to be able to complete the exercise.


Instructor Note

You might like to make a copy of the template CodiMD notetaking page and share your link with trainees so that you can take notes together during the training.

Lesson Design

Trainer Note

Trainees should have received the questions above in advance and arrived at the training with notes prepared. Where multiple trainees are working on the same lesson project, ask for a volunteer or call on someone to represent their team, leaving space afterwards for their team-mates to speak up if their answers differ.

The main objectives of this discussion are:

  • to ensure that the members of each collaborative team share a common vision for the lesson they want to create
  • to help Trainers and collaborators understand each trainee’s motivation for attending the training and building their lesson

Identifying Your Target Audience


Defining Lesson Objectives/Outcomes

Markdown Table Template for Exercise

You may find this template of a Markdown table useful to share with your trainees before they complete the next exercise.


| Objective | Action verb? | Specific | Measurable | Attainable |
| 1         |              |          |            |            |
| 2         |              |          |            |            |
| 3         |              |          |            |            |

Note: if you are using the template CodiMD for notes, you will find this template table for the exercise included there.

If you are using Etherpad for collaborative notes in your training, you can use the template table for Etherpad instead.



The Carpentries Workbench

Instructor Note

Remind learners to paste URL of their lesson repository and the rendered version of the lesson to the collaborative document.

Activating GitHub Pages

We need to tell GitHub to begin serving the lesson website via GitHub Pages. To do this, navigate to Settings, then choose Pages from the left sidebar. Under Source, choose the gh-pages branch, leave the folder set to / (root), and click Save. You may copy the URL in this box, this will be the address of your lesson site.

Orientation for GitHub Novices

  1. For trainees unfamiliar with the relationship between a source repository and rendered website, it is important to show the default version of the lesson website now i.e. before beginning to edit config.yaml.
  2. It is also recommended to take time at this point to demonstrate step-by-step how to edit files in the GitHub web interface.

Instructor Note

Be careful here to ensure that participants who are collaborating on the same repository do not create conflicts e.g. by editing the same file or creating files with identical names.

Troubleshoot Lesson Builds (~10 mins)

This is a good opportunity to pause and check in on how well trainees’ lesson builds are running. If anyone is having trouble with their workflows, ask them to share their screen and try following the troubleshooting steps to diagnose and fix the issue.

This is also a good opporunity to show what the GitHub actions look like when they are in progress, succeed, or fail if you haven’t already.


Defining Episode Objectives


Designing Exercises

Implementing Exercises


Example Data and Narrative

Instructor Note

Outline covering the above paragraph - also used in CodiMD template.

Dataset Considerations

  • Ethical use (see prompts below)
  • License - CC0 Recommended
  • Complexity - Is it easy to understand? Is it sufficiently authentic?
  • Number and types of variables

Questions about Ethical Use of Datasets

  • Does the data contain personally identifiable information?
  • Was the data collected without permission from the groups or individuals included?
  • Will the data be upsetting to learners in the workshop?


How to Write a Lesson

Trainer Note

To get started on the discussion part, try reading out an interesting response and asking for more detail from the trainee who wrote it. Ask one of the other trainers/helpers to take notes of this discussion in the collaborative note-taking document.

This is a good opportunity to remind trainees about how counter-productive it can be to try to cover more content than the time allows. (See the earlier section on lesson scope.)

Instructor Note

This is the hidden note! Thanks for developing new incubator lessons for others to use!

Instructor Note

May want to point out that the answers in the current version of this exercise do not have diagnostic power.


How we Operate

Preparing to Teach


Adding Design Notes to the Lesson Site

If trainees would like to add the Design Notes document they have been working on to their lesson site, they can do the following:

  1. replace the first 13 lines with
title: Lesson Design Notes
  1. save the file to the instructors/ directory, and any images used in the file to the episodes/fig directory (the paths to source files for images will need to be adjusted to begin episodes/fig/)
  2. add the filename below instructors: in config.yml as they have done for episode filenames below episodes: previously. For example, if their file is saved with the name ‘’:


# Information for Instructors

This will make the page accessible from the ‘More’ dropdown in Instructor View.

Note that concept maps with GraphViz are not currently supported by the lesson infrastructure, so any concept maps added to the document on CodiMD will not be displayed correctly on the lesson site.

Reflecting on Trial Runs

Instructor Note

This episode picks-up after a long break in training for learners, you may need to remind them of the following expectations as part of training.

  • The Carpentries Code of Conduct
  • How to get in the queue to participate - hand-raising, typing in chat, etc.
  • Microphones muted when you aren’t speaking (if virtual)
  • Any other expectations for interaction

Discussion format

For online trainings, Trainers have found it beneficial to give participants the first 5 minutes together in a breakout room, to re-familiarise themselves with the notes from their Trial Runs and discuss what they are going to report out to the rest of the group.

In trainings with a larger cohort of participants, try asking groups to assign a reporter who will be responsible for summarising their experience and answering the discussion questions on behalf of their collaborators.


Collaborating with Your Team


Collaborating with Newcomers

Time management tip: share the next spoiler, do not teach it

The next spoiler contains a lot of information, and can require a lot of time to discuss fully while training. We recommend that you do not dwell on these details while teaching unless you have time to spare.

Instead, you could share a link to the spoiler and mention to trainees that this information can be helpful if they are struggling with GitHub notifications.

Project Management and Governance

Final Wrap-up