<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<title>Software Carpentry: </title>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico" />
<link rel="stylesheet" href="css/bootstrap/bootstrap.css" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="stylesheet" href="css/bootstrap/bootstrap-responsive.css" />
<link rel="stylesheet" type="text/css" href="css/swc.css" />
<link rel="alternate" type="application/rss+xml" title="Software Carpentry Blog" href="http://software-carpentry.org/feed.xml"/>
<meta charset="UTF-8" />
<!-- HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
</head>
<body>
<div class="container">
<div class="banner">
<a href="http://software-carpentry.org" title="Software Carpentry">
<img alt="Software Carpentry banner" src="img/software-carpentry-banner.png" />
</a>
</div>
<div class="row-fluid">
<div class="span10 offset1">
<h1 class="title"></h1>
<h1 id="lesson-layout">Lesson Layout</h1>
<p>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).</p>
<ol style="list-style-type: decimal">
<li><p><code>README.md</code>: initially a copy of this file. It should be overwritten with short description of the lesson.</p></li>
<li><p>Other files in the root directory: the source of the lesson's web pages (and possibly auxiliary files like IPython Notebooks and R Markdown files).</p></li>
<li><p><code>code/</code>, <code>data/</code>, and <code>fig/</code>: sub-directories containing sample code, data files, and figures. See "Code, Data, and Figures" below.</p></li>
<li><p><code>css/</code>, <code>img/</code>, <code>js/</code>, and <code>deck.js/</code>: style sheets, artwork, and Javascript used in the lesson's web site. See "Support Files" below.</p></li>
<li><p><code>_layouts/</code> and <code>_includes/</code>: page templates and inclusions. See "Support Files" below.</p></li>
<li><p><code>tools/</code>: tools for managing lessons. See "Tools" below.</p></li>
</ol>
<h1 id="code-data-and-figures">Code, Data, and Figures</h1>
<p>All of the software samples used in the lesson must go in a directory called <code>code/</code>. Stand-alone data files must go in a directory called <code>data/</code>. Groups of related data files must be put together in a sub-directory of <code>data/</code> with a meaningful (short) name. Figures, plots, and diagrams used in the lessons must go in a <code>fig/</code> directory.</p>
<p><strong>Notes:</strong></p>
<ol style="list-style-type: decimal">
<li><p>This mirrors the layout a scientist would use for actual work. However, it may cause novice learners problems. If a program is in <code>code/a.py</code>, and contains a reference to a data file <code>../data/b.csv</code>, then if the user runs the program from the root directory using <code>python code/a.py</code>, it will be unable to find the data file (since the program's working directory will be the root directory, not the <code>data</code> directory).</p></li>
<li><p>IPython Notebooks and R Markdown files, which are both code and the source for web pages, should go in the root directory. These will not be checked by our validation tool, or indexed by other tools we plan to build.</p></li>
<li><p>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.</p></li>
</ol>
<h1 id="support-files">Support Files</h1>
<p>Files used to display the lesson, such as artwork, CSS, and Javascript, are stored in <code>img/</code>, <code>css/</code>, and <code>js/</code> directories of their own, while the <code>deck.js/</code> directory contains files used to make HTML slideshows. We keep website artwork in the <code>img/</code> directory separate from figures used in the lesson (which are stored in <code>fig/</code>) to make it simple to update the former automatically. Most authors should not need to modify any of the support files themselves.</p>
<p>The <code>_layouts/</code> directory holds the page templates used to translate Markdown to HTML, while the <code>_includes/</code> directory holds snippets of HTML that are used in several page layouts. These directories have underscores at the start of their names to be consistent with Jekyll's naming conventions, but the files they contain are for Pandoc.</p>
<h1 id="tools">Tools</h1>
<p>The <code>tools/</code> directory contains tools to help create and maintain lessons:</p>
<ul>
<li><code>tools/check</code>: make sure that everything is formatted properly, and print error messages identifying problems if it's not.</li>
</ul>
<h1 id="pages">Pages</h1>
<p>The root directory holds the content of the lesson, and must contain:</p>
<ol style="list-style-type: decimal">
<li><p><code>Makefile</code>: contains commands to check, preview, and update the repository. Authors should not need to modify this file.</p></li>
<li><p><code>index.md</code>: the home page for the lesson. (See "Home Page" below.)</p></li>
<li><p><code>dd-slug.md</code>: the topics in the lesson. <code>dd</code> is a sequence number such as <code>01</code>, <code>02</code>, etc., and <code>slug</code> is an abbreviated single-word mnemonic for the topic. Thus, <code>03-filesys.md</code> is the third topic in this lesson, and is about the filesystem. (Note that we use hyphens rather than underscores in filenames.) See "Topics" below.</p></li>
<li><p><code>motivation.md</code>: slides for a short introductory presentation (three minutes or less) explaining what the lesson is about and why people would want to learn it. See "Introductory Slides" below.</p></li>
<li><p><code>reference.md</code>: a cheat sheet summarizing key terms and commands, syntax, etc., that can be printed and given to learners. See "Reference Guide" below.</p></li>
<li><p><code>discussion.md</code>: notes about more advanced ideas that would distract from the main lesson, and pointers to where to go next. See "Discussion Page" below.</p></li>
<li><p><code>instructors.md</code>: the instructor's guide for the lesson. See "Instructor's Guide" below.</p></li>
</ol>
<p>Note that the lesson's title is repeated in several files. We could put this in the Makefile, and insert it into pages when compiling, but then authors would have to edit the Makefile (which we want to avoid). We could also put it in some sort of configuration file, but again, we're trying to avoid those.</p>
<h2 id="home-page">Home Page</h2>
<p><code>index.md</code> must be structured as follows:</p>
<pre><code>---
layout: lesson
title: Lesson Title
---
Paragraph(s) of introductory material.
> ## Prerequisites {.prereq}
>
> What learners need to know before tackling this lesson.
## Topics
1. [Topic Title 1](01-slug.html)
2. [Topic Title 2](02-slug.html)
## Other Resources
* [Motivation](motivation.html)
* [Reference Guide](reference.html)
* [Next Steps](discussion.html)
* [Instructor's Guide](instructors.html)</code></pre>
<p><strong>Notes:</strong></p>
<ol style="list-style-type: decimal">
<li><p>The description of prerequisites is prose for human consumption, not a machine-comprehensible list of dependencies. We may supplement the former with the latter once we have more experience with this lesson format and know what we actually want to do.</p></li>
<li><p>Software installation and configuration instructions <em>aren't</em> in the lesson, since they may be shared with other lessons. They will be stored centrally on the Software Carpentry web site and linked from the lessons that need them.</p></li>
</ol>
<h2 id="topics">Topics</h2>
<p>Each topic page must be structured as follows:</p>
<pre><code>---
layout: page
title: Lesson Title
subtitle: Topic Title
minutes: 10
---
> ## Learning Objectives
>
> * Learning objective 1
> * Learning objective 2
Paragraphs of text --- possibly including **definitions** ---
mixed with:
~~~ {.python}
some code:
to be displayed
~~~
and:
~~~ {.output}
output
from
program
~~~
and:
~~~ {.error}
error reports from programs (if any)
~~~
and possibly including some of these:
> ## Callout Box {.callout}
>
> An aside of some kind.
and one or more of these:
> ## Challenge Title {.challenge}
>
> Description of a single challenge.
> There may be several challenges.</code></pre>
<p><strong>Notes:</strong></p>
<ol style="list-style-type: decimal">
<li><p>The "expected time" heading is called minutes to encourage people to create topics that are short (10-15 minutes at most).</p></li>
<li><p>There are no sub-headings inside a topic other than the ones shown. (If a topic needs sub-headings, it should be broken into two or more topics.)</p></li>
<li><p>Every challenge should relate explicitly back to a learning objective.</p></li>
<li><p>Definitions of terms are marked in <strong>bold</strong> (like <code>**this**</code>). Nothing else should be marked as bold text --- use <em>italics</em> for for all other emphasis.</p></li>
</ol>
<h2 id="motivational-slides">Motivational Slides</h2>
<p>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. The slides must be laid out like this:</p>
<pre><code>---
layout: slides
title: Why Make?
---
<section class="slide">
## Why This Topic?
</section>
<section class="slide">
## Some Other Point
</section></code></pre>
<p><strong>Notes:</strong></p>
<ol style="list-style-type: decimal">
<li><p>This is the one place where we <em>must</em> use HTML tags in our Markdown (to delimit slides). Everything inside the section markers should be Markdown if possible.</p></li>
<li><p>We use <a href="http://imakewebthings.com/deck.js/">deck.js</a> for our slides as it is simpler and prettier than alternatives like <a href="http://lab.hakim.se/reveal-js/">reveal.js</a>.</p></li>
</ol>
<h2 id="reference-guide">Reference Guide</h2>
<p>The reference guide is a cheat sheet for learners to print, doodle on, and take away. Its format 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).</p>
<p>The last section of the reference guide must be a glossary laid out as a definition list:</p>
<pre><code>---
layout: page
title: Lesson Title
subtitle: Reference
---
...commands and examples...
## Glossary
Key Word 1
: Definition of first term
Key Word 2
: Definition of second term</code></pre>
<h2 id="discussion-page">Discussion Page</h2>
<p>The discussion page</p>
<pre><code>---
layout: page
title: Lesson Title
subtitle: Discussion
---
* First point of general discussion.
This may span several paragraphs.
* Second point of general discussion.</code></pre>
<h2 id="instructors-guide">Instructor's Guide</h2>
<p>Learners may go through 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:</p>
<pre><code>---
layout: page
title: Lesson Title
subtitle: Instructor's Guide
---
## Legend
One or more paragraphs laying out the lesson's legend (i.e., the story
behind its running example).
## Overall
* Point
* Point
## [Topic Title 1](01-slug.html)
* Point
* Point
1. Discussion of first challenge.
2. Discussion of second challenge.
## [Topic Title 2](02-slug.html)
* Point
* Point
1. Discussion of first challenge.
2. Discussion of second challenge.</code></pre>
<p><strong>Notes:</strong></p>
<ol style="list-style-type: decimal">
<li><p>The topic headings must match the topic titles. (Yes, we could define these as variables in a configuration file and refer to those variables everywhere, but in this case, repetition will be a lot easier to read, and our validator can check that the titles line up.)</p></li>
<li><p>The points can be anything: specific ways to introduce ideas, common mistakes learners make and how to get out of them, or anything else.</p></li>
<li><p>Full solutions to the challenges do not have to be presented, but every challenge should be discussed, and that discussion should mention how long it typically takes to do. (Those estimates do not go in the challenge itself, since they can increase learners' stress levels.)</p></li>
</ol>
</div>
</div>
<div class="footer">
<a class="label swc-blue-bg" href="mailto:admin@software-carpentry.org">Email</a>
<a class="label swc-blue-bg" href="http://github.com/swcarpentry">GitHub</a>
<a class="label swc-blue-bg" href="LICENSE.html">License</a>
<a class="bugreport label swc-blue-bg" href="mailto:admin@software-carpentry.org?subject=bug%20in%20{{page.path}}">Bug Report</a>
</div>
</div>
<!-- Javascript placed at the end of the document so the pages load faster -->
<script src="http://software-carpentry.org/v5/js/jquery-1.9.1.min.js"></script>
<script src="http://software-carpentry.org/v5/js/bootstrap/bootstrap.min.js"></script>
</body>
</html>