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 5 Developing content

At this point in the lesson development process, you should have a list of the core skills that your lesson will teach, along with a set of exercises that you will incorporate into your lesson. If you’ve taken the time to go through these steps, the remaining parts of the development process will be much more straightforward and take less time than if you try to start with developing content. Its ok if your list of skills and set of exercises changes a little as you develop your lesson content – none of us get it right on the first try – however, if you’ve invested time in the first two steps of the backward design process, these changes should be fairly small.

Now that we’re ready to start writing the lesson material, it’s worth laying out some of the fundamental elements of a Carpentries lesson. These elements are covered in much more detail in a later chapter, so we will focus here on the bare minimum you need to know to get started. It’s perfectly ok to work through some or all of the steps described in this chapter before worrying about the logistics of putting your materials up on GitHub, but if you’re working with multiple authors, it may be worth putting your materials on GitHub at this stage, to make collaboration easier. The Technological Introductions chapter can get you started with hosting your lesson on GitHub.

5.1 Fundamental elements

The bulk of a Carpentries lesson consists of exercises, example code chunks, and narrative text. You have already developed many or all of the exercises you will include in your lesson, so congratulations on being one-third done with content development! The remaining two major components of the lesson are described below.

5.1.1 Code chunks

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.

Since you already know the structure of your dataset, and already have your exercises in place, it’s fairly straightforward to create the code chunks for your lesson. Starting with the first exercise, make a list of each of the commands and syntax elements that learners need to be familiar with in order to solve the exercise. For example, the first exercise in the Data Carpentry lesson Introduction to the Command Line for Genomics asks learners to:

Challenge

Use the -l option for the ls command to display more information for each item in the directory. What is one piece of additional information this long format gives you that you don’t see with the bare ls command?

In order to solve this challenge, learners need to know the following (in approximately reverse order):

That options come after the command (e.g. ls -l not -l ls).
How to find the manual page for ls to understand the output.
What the ls command does in its bare form.
How to navigate to the right directory.
How to tell what directory they’re in.
How to open the bash shell on their machines.

That’s six concepts or pieces of information that learners need to have to answer this challenge! If it didn’t seem that complex to you, please revisit the idea of expert awareness gap in our Instructor Training curriculum.

With this list, you can now construct the pieces of code that an Instructor will need to walk learners through before this first exercise. Those pieces of code (in the same order as above - the reverse order they would be used in a lesson), are something like:

ls -F (or any other commonly used ls option other than ls)
man ls (or man cd or man pwd)
ls
cd
pwd
Not a code chunk, but a demonstration of how to open the bash shell on the Instructor’s machine.

You now have your first set of code chunks corresponding with your first exercise. Put these in reverse order and you’re well on your way to writing your lesson!

5.1.2 Narrative text

The narrative text component of the lesson provides a guide for Instructors to use while teaching. It should provide a clear and complete narrative that (in theory) could be used by an Instructor as a script for the lesson. Instructors will not actually be using this text as a script, because they will be responding to the needs of their particular learners in real time, both in terms of the level of detail they go into, and in how they answer questions. However, this text should give Instructors a starting point for explaining the lesson content. This text can also be used by independent learners to work through the lesson materials outside of a workshop setting.

Wait to start writing your narrative text until you’re fairly confident about the set of code chunks you’ve written. Any changes to the code chunks will require corresponding changes to the text, which can become time consuming. For the set of code chunks above, we would need to write a short explanation for each step. For example, the narrative corresponding to the ls code chunk in this lesson is:

We can see files and subdirectories are in this directory by running ls, which stands for “listing”:

ls

ls prints the names of the files and directories in the current directory in alphabetical order, arranged neatly into columns.

And the narrative corresponding to the man ls command in this lesson is:

ls has lots of other options. To find out what they are, we can type:

man ls

Some manual files are very long. You can scroll through the file using your keyboard’s down arrow or use the Space key to go forward one page and the b key to go backwards one page. When you are done reading, hit q to quit.

Narrative text should be as short as possible and should avoid discussion of edge cases or caveats. If there are important caveats, those can be included in a callout box (see the Technological Introductions chapter for formatting details of callout boxes). Only include callouts for cases a significant fraction of your learners will experience in their work. It’s very easy to clutter the lesson and overwhelm learners.

5.1.3 Considering cognitive load

You may have noticed that the exercise we dissected above required six pieces of knowledge to solve. This number isn’t random! Cognitive science research has clearly established that human working memory is limited, and can only handle a small number of separate items of information at once. This number is generally considered to be 7 plus or minus 2, but recent research has suggested it may be even smaller. If learners are presented with more than this many discrete pieces of information, they will not be able to keep all those pieces in mind simultaneously. Once they have had an opportunity to work with those pieces of information, their brains will create connections that will allow them to store the information in long-term memory and retrieve it as needed. This is why it is essential to include frequent exercises, spread throughout the lesson at regular intervals with only ~5 intervening new concepts. If you find that you need more than about this many code chunks between exercises, you probably need to either simplify your exercise, or add another exercise in between.

5.2 Supporting elements

Once you’ve created your exercises and written your code chunks and narrative, your lesson is nearly complete! There are a few remaining elements that support the main episode content by providing a clear outline of content for both learners and Instructors. These supporting elements are learning objectives, key points, and framing questions. When you create your lesson repository from The Carpentries template, there will be sections for you to enter these supporting items for each episode. The template will extract these elements and embed them in the rendered lesson webpage. For details, see the Technological Introductions chapter.

5.2.1 Learning objectives

Great news - you’ve already almost completed writing your learning objectives! The skills list that you developed for your lesson can be easily transformed to learning objectives. Learning objectives are statements that communicate to learners the skills they can expect to gain from the lesson. They should always be framed from the learner’s perspective and use action words. In other words, they should emphasize what a learner will be able to do not what they will know. For example, the first episode of the Data Carpentry lesson Introduction to the Command Line for Genomics includes the following learning objectives:

Describe key reasons for learning shell.
Navigate your file system using the command line.
Access and read help files for bash programs and use help files to identify useful command options.
Demonstrate the use of tab completion, and explain its advantages.

If you didn’t use action words when creating your skills list, there are many existing resources available that list action verbs associated with different levels of learning (one example). For our purposes, the differences among these levels isn’t as important as using action verbs in defining your learning objectives. When learning objectives are framed in this way, learners should be able to self-evaluate whether they have completed each learning objective and concretely understand what they have gained from the lesson or what they still need to work on.

Keeping in mind our discussion of cognitive load above, each episode should have ~5-7 learning objectives. If you have more than that, you should consider splitting the material into multiple episodes.

5.2.2 Key points

While learning objectives communicate to learners the skills they should develop by working through each episode, key points summarize the main pieces of knowledge that learners should remember after completing the episode. These should also be limited to ~5-7 items. For the episode we’ve been considering in the Data Carpentry lesson Introduction to the Command Line for Genomics, the key points are:

“The shell gives you the ability to work more efficiently by using keyboard commands rather than a GUI.”
“Useful commands for navigating your file system include: ls, pwd, and cd.”
“Most commands take options (flags) which begin with a -.”
“Tab completion can reduce errors from mistyping and make work more efficient in the shell.”

The Carpentries lesson template automatically creates a reference page that includes all of the key points for each episode in the lesson. Key points should be specific enough that learners are able to use this reference page as review.

5.2.3 Framing questions

The final supporting component for the lesson are the framing questions for each episode. These questions provide a high-level overview of the motivations for learning the lesson content. There should be ~1-3 questions for each episode, which should correspond to questions that your target audience ask themselves about their own workflows. The set of framing questions for the Data Carpentry lesson Introduction to the Command Line for Genomics includes:

How can I view and search file contents?
How can I create, copy and delete files and directories?
How can I control who has permission to modify a file?
How can I repeat recently used commands?

The lesson template automatically creates an overview page for the lesson, which includes the framing questions for each episode.