README.md

lesson-template

This repository is the template for Software Carpentry lessons. To create a new lesson:

1. Create a new (empty) repository on GitHub.
2. Clone that empty repository to your desktop.
3. Create a gh-pages branch in that repository.
4. Add this repository as a remote called template.
5. Pull the content of this repository into your repository.
6. Create and edit files (explained below).
7. Run the validator to make sure everything is formatted correctly.
8. Push your changes to GitHub for viewing.
9. Tell us where your lesson is so that we can use it and help you improve it.

Dependencies

1. [Install Pandoc]http://www.johnmacfarlane.net/pandoc/installing.html)

2. Install pandocfilters, a python module that helps with writing filters for pandoc:

   pip install pandocfilters

Why Use a Template?

We organize our lessons in a standard way so that:

1. To give guidance to people who aren't experienced instructional designers. Requiring learning objectives, challenges, and a short glossary tells people what they ought to create.

2. It's easy to find things in lessons written by different people.

3. People using lessons written by different people can easily given them the same look and feel.

4. Contributors know where to put things when they are extending or modifying lessons.

5. Content can be checked mechanically.

Instead of putting the whole lesson in one page, authors should create one short page per topic. Each topic should take 10-15 minutes to cover, and that coverage to include:

1. Explain the topic's objectives.

2. Perform the material. (We expect instructors to code live, not to put lesson notes or slides on the screen.)

3. Do one or more challenges depending on time.

Along with the lesson materials themselves, each lesson must contain:

• Introductory slides to give learners a sense of where the next two or three hours are going to take them.

• A reference guide that learners can use during the lesson and take away afterward. This must include a glossary of terms, not only to help learners, but also to help lesson authors summarize what the lesson actually covers.

• A discussion page that mentions more advanced ideas and tells learners where to go next.

• An instructor's guide that presents the lesson's legend (or back story), summarizes our experiences with the lesson, and discusses solutions to the challenge exercises. We ask everyone who teaches for us to review and update the instructor's guide for each lesson they taught after each workshop.

  Note that the this means the solutions to the lesson's challenge exercises will be up on the web. We have chosen to do this because we believe in openness, and because there's no point trying to hide something that's in a publicly-readable repository.

Authors may retain copyright on their lessons, but we ask that all lessons be published under the Creative Commons - Attribution (CC-BY) license, or put in the public domain (CC-0), to permit remixing.

Background

There are a few things you need to know in order to understand why this template is organized the way it is:

1. Git uses the term clone to mean "a copy of a repository". GitHub uses the term fork to mean, "a copy of a GitHub-hosted repo that is also hosted on GitHub", and the term clone to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". In both cases, the duplicate has a remote called origin that points to the original repo; other remotes can be added manually.

2. A user on GitHub can only have one fork of a particular repo. This is a problem for us because an author may be involved in writing several lessons, each of which has its own website repo. Those website repositories ought to be forks of this one, but since GitHub doesn't allow that, we've had to find a workaround.

3. If a repository has a branch called gh-pages (which stands for "GitHub pages"), then GitHub uses the HTML and Markdown files in that branch to create a website for the repository. If the repository's URL is http://github.com/darwin/finches, the URL for the website is http://darwin.github.io/finches.

4. We use Markdown for writing pages because it's simple to learn, and isn't tied to any specific language (the ReStructured Text format popular in the Python world, for example, is a complete unknown to R programmers). If authors want to use something else to author their lessons (e.g., IPython Notebooks), it's up to them to generate and commit Markdown formatted according to the rules below.

   Note: we do not prescribe what tools instructors should use when actually teaching. The IPython Notebook, Python IDEs like Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all equally welcome up on stage --- all we specify is the format of the lesson notes.

5. We use Pandoc to process pages instead of Jekyll (GitHub's default conversion tool) because Pandoc supports a much richer dialect of Markdown than Jekyll. Like Jekyll, Pandoc looks for a header at the top of each page formatted like this:

   ---
   variable: value
   other_variable: other_value
   ---
   ...stuff in the page...

   and inserts the values of those variables into the page when formatting this. Lesson authors will usually not have to worry about this.

6. Using Pandoc instead of Jekyll means that we have to compile our Markdown into HTML on our own machines and commit it to the gh-pages branch of the lesson's GitHub repository. In order to keep our source files and generated files separate, we put our source files in a sub-directory called pages, and compile them "upward" into the root directory of the lesson's repository.

   Note: while it's usually considered bad practice to put computer-generated files under version control, the HTML pages put into the lesson's root directory by Pandoc must be committed to version control in order for the lesson to be displayed properly on GitHub.

7. In order to display properly, our generated HTML pages need artwork, CSS style files, and a few bits of Javascript. We could load these from the web, but that would make offline authoring difficult. Instead, each lesson's repository has a copy of these files, and a way of updating them (and only them) on demand.

One final note: we try not to put HTML inside Markdown because it's ugly to read and write, and error-prone to process. Instead, we put things that ought to be in <div> blocks, like the learning objectives and challenge exercises, in blocks indented with >, and do a bit of post-processing to attach the right CSS classes to these blocks.

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).

1. README.md: initially a copy of this file. It should be overwritten with short description of the lesson.

2. pages/: a sub-directory containing the source of the lesson's website. See "Pages" below.

3. code/, data/, and fig/: sub-directories containing sample code, data files, and figures. See "Code, Data, and Figures" below.

4. css/, img/, and js/: style sheets, artwork, and Javascript used in the lesson's web site. See "Support Files" below.

5. _layouts/ and _includes/: page templates and inclusions. See "Support Files" below.

6. tools/: tools for managing lessons. See "Tools" below.