A New Lesson Template, Version 2


Update: this post now includes feedback from participants in the instructor training session run at TGAC on Oct 22-23, 2014. Please see the bottom of this page for their comments.

Thanks to everyone for their feedback on the first draft of our new template for lessons. The major suggestions were:

With all that in mind, here’s another cut at the template–as before, we’d be grateful for comments. Note that this post mingles description of “what” with explanation of “why”; the final guide for people building lessons will disentangle them to make the former easier to follow.

Note also that Trevor Bekolay has drafted an implementation at https://github.com/tbekolay/swc-template for people who’d like to see what the template would look like in practice. There’s still work to do (see below), but it’s a great start. Thanks to Trevor, the other Trevor, Erik with a ‘k’, Molly, Emily, Karin, Rémi, and Andromeda for their feedback.

To Do


Design Choices

Justification and Tutorial

The main Software Carpentry website will contain a one-page tutorial explaining (a) how to create and update lessons and (b) how the various parts of the template support better teaching. A sketch of the second of these is:

Overall Layout

Each lesson is stored in a directory laid out as described below. That directory is a self-contained Git repository (i.e., there are no submodules or clever tricks with symbolic links).

Home Page

index.md must be structured as follows:

layout: lesson
title: Lesson Title
keywords: ["some", "key terms", "in a list"]
Paragraph of introductory material.

> ## Prerequisites
> A short paragraph describing what learners need to know
> before tackling this lesson.

## Topics

* [Topic Title 1](01-slug.html)
* [Topic Title 2](02-slug.html)

## Other Resources

* [Introduction](intro.html)
* [Reference Guide](reference.html)
* [Instructor's Guide](guide.html)



Each topic must be structured as follows:

layout: topic
title: Topic Title
minutes: MM
> ## Learning Objectives {.objectives}
> * Learning objective 1
> * Learning objective 2

Paragraphs of text mixed with:

~~~ {.python}
some code:
    to be displayed
~~~ {.output}
~~~ {.error}
error reports from program (if any)

and possibly including:

> ## Callout Box {.callout}
> An aside of some kind.

> ## Challenge Title {.challenge}
> Description of a single challenge.
> There may be several challenges.


Introductory Slides

Every lesson must include a short slide deck suitable for a short presentation (3 minutes or less) that the instructor can use to explain to learners how knowing the subject will help them. Slides are written in Markdown, and compiled into HTML for use with reveal.js.


Reference Guide

The reference guide is a cheat sheet for learners to print, doodle on, and take away. The format of the actual guide is deliberately unconstrained for now, since we’ll need to see a few before we can decide how they ought to be laid out (or whether they need to be laid out the same way at all).

The last thing in it must be a Level-2 heading called “Glossary” followed by definitions of key terms Each definition must be formatted as a separate blockquote indented with > signs:

layout: reference
…commands and examples…

## Glossary

> **Key Word 1**: the definition
> relevant to the lesson.

> **Key Word 2**: the definition
> relevant to the lesson.

Again, we use blockquotes because standard [sic] Markdown doesn’t have a graceful syntax for <div> blocks. If definition lists become part of CommonMark, or if we standardize on Pandoc as our translation engine, we can use definition lists here instead of hacking around with blockquotes.

Instructor’s Guide

Many learners will go through the lessons outside of class, so it seems best to keep material for instructors in a separate document, rather than interleaved in the lesson itself. Its structure is:

title: Instructor's Guide
## Overall

One or more paragraphs laying out the lesson's legend.

## General Points

* Point
* Point

## Topic 1

* Point
* Point

## Topic 2

* Point
* Point


Software, Data, and Images

All of the software samples used in the lesson must go in a directory called code/. Stand-alone data files must go in a directory called data/. Groups of related data files must be put together in a sub-directory of data/ with a meaningful (short) name.

Images used in the lessons must go in an img/ directory. We strongly prefer SVG for line drawings, since they are smaller, scale better, and are easier to edit. Screenshots and other raster images must be PNG or JPEG format.



The tools/ directory contains tool to help create and maintain lessons:


The template still contains _layouts/ and _includes/ directories for page layout templates and standard inclusions. These are needed to support lesson preview.

Major Changes

Feedback from TGAC Instructor Trainees

Participants in the instructor training session run at TGAC on Oct 22-23 gave us feedback on the content shown above. Their points are listed below; we’ll try to factor them into the final template.


  • Details +2
  • Lots of technical detail
  • Enables flexibility - adding contents
  • Markdown
  • Helps to structure / think about content
  • Good outline of what you want to do
  • Good organisation
  • Enough detail for somebody who doesn't have much experience
  • Uncomplicated visually
  • Required variables section
  • Proper highlighting for the syntax part
  • Clearly listed variables


  • Assumed knowledge (keywords) +2
  • Not much introduction +2
  • Overwhelming
  • Some terms jargon unclear
  • Not live yet so you can't check if works
  • Mixed instructions (website + Jekyll info)
  • Text on the lesson template needs reordering (restucturing)
  • See Markdown rendered so that it's easier to review
  • Key info down at the bottom
  • More visual info
  • No "Get it touch" info
  • Customizing lessons badly explained
  • Which md and translators to use
  • Colours (background + foreground)
  • example.edu for email


  • Maybe two different overviews (depending on the audience) +2
  • Why these engineering choices were made? (if that was supposed to be simple)
  • Troubleshooting?
  • Shortcut to the "how to set it up and skip the whole info"?
  • How is feedback to lessons made available to others?
  • Metasection on each lesson - which audience it is particularly working well with?
  • Why should we create our own website?