Updating based on feedback

    [file an issue](https://github.com/swcarpentry/lesson-template/issues?q=is%3Aopen+is%3Aissue)

    or [mail us](mailto:admin@software-carpentry.org).

*   *Why does the lesson repository have to be created using import? Why not fork `lesson-template` on GitHub?*

*   *Why does the new lesson's repository have to be created using import? Why not fork `lesson-template` on GitHub?*

    Because any particular user can only have one fork of a repository,

    but instructors frequently need to work on several workshops at once.

## Motivational Slides

Every lesson must include a short slide deck suitable for a short

Every lesson must include a short slide deck in `motivation.md` 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:

use level-2 headings as slide titles, but may use anything within the slide:

    ---

    layout: slides

    title: Lesson Title

    subtitle: Motivation

    ---

    <section class="slide">

    ## Why This Topic?

    </section>

    ## Our Mission

    <section class="slide">

    ## Some Other Point

    </section>

    We make scientists and engineering more productive

    by teaching them basic computing skills.

**Notes:**

    ## The Problem

    - Surveyed 1972 scientists in 2008.

    - "How do you use computers?"

    - "How did you learn what you know?"

1.  This is the one place where we *must* use HTML tags in our Markdown

    (to delimit slides).  Everything inside the section markers should

    be Markdown if possible.

**Notes:**

2.  We use [deck.js](http://imakewebthings.com/deck.js/) for our slides

1.  We use [deck.js](http://imakewebthings.com/deck.js/) for our slides

    as it is simpler and prettier than alternatives like

    [reveal.js](http://lab.hakim.se/reveal-js/).

3.  For examples of slideshows, please see the

2.  For examples of slideshows, please see the

    [slideshow repository](https://github.com/swcarpentry/slideshows).

## Reference Guide

The reference guide is a cheat sheet for learners to print, doodle on,

The reference guide in `reference.md` 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).

## Discussion Page

The discussion page

The discussion page in `discussion.md` is meant to contain links to

further reading, supplementary material that classes usually won't

get to, and so on.  Sections must use level-2 headings, but the

content is otherwise unconstrained:

    ---

    layout: page

    title: Lesson Title

    subtitle: Discussion

    ---

    *   First point of general discussion.

    ## Something That May Be Useful

    Paragraphs of general discussion

        This may span several paragraphs.

    ## Something Else

    *   Second point of general discussion.

    More general discussion, with links.

Note: the discussion page is not meant to be more lesson material, so

it should not contain challenges and the like.  Instead, it should

give pointers to other lessons and tools that learners might find

useful, etc.  Its format is deliberately vague for now: once we have

more experience with our lesson template, we will provide more

guidance on how to lay out this file.  Until then, please do whatever

feels best.

Note: the discussion page is not lesson material, so it should not

contain challenges and the like.  Its format is deliberately vague for

now: once we have more experience with our lesson template, we will

provide more guidance on how to lay out this file.  Until then, please

do whatever feels best.

## Instructor's Guide

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:

keep material for instructors in a separate document called

`instructors.md`, rather than interleaved in the lesson itself.  Its

structure is:

    ---

    layout: page

lesson-example

==============

This repository is an example of a lesson created using

the [Software Carpentry][swc] [lesson template][swc-lesson-template].

This repository shows how to create a lesson using

the [Software Carpentry][swc] [lesson template][swc-lesson-template],

and is itself an example of the use of that template.

1.  Do *not* fork this repository directly on GitHub.

    Instead, please follow the instructions below

2.  Once you have created the repository,

    please go through [the layout instructions](LAYOUT.md) to format your lesson.

Please *do your work in your repository's `gh-pages` branch*,

since that is what is [automatically published as a website by GitHub](https://help.github.com/articles/creating-project-pages-manually/).

3.  Please keep the master copy of your lesson in your repository's `gh-pages` branch,

    since that is what is

    [automatically published as a website by GitHub](https://help.github.com/articles/creating-project-pages-manually/).

    To simplify reviewing,

    please make changes in feature branches

    and then submit pull requests against the `gh-pages` branch of your lesson's repository.

## Manual Setup

## Creating Your Lesson's Repository

We will assume that your user ID is `gvwilson` and the name of your

lesson is `data-cleanup`.

    When the process is done,

    you can click "Continue to repository" to visit your newly-created repository.

**Note:**

some people have had intermittent errors during the import process,

possibly because of the network timing out.

If you experience a problem, please re-try;

if the problem persists,

please [get in touch](#getting-and-giving-help).

7.  Clone your newly-created repository to your desktop:

    ~~~

    $ git clone -b gh-pages git@github.com:gvwilson/data-cleanup.git

    $ git clone -b gh-pages https://github.com/gvwilson/data-cleanup.git

    ~~~

8.  Go into that directory using

    Note that the URL for your lesson will be different than the one above.

8.  Go into that directory using:

    ~~~

    $ cd data-cleanup

    ~~~

    Note that the name of your directory will be different,

    since your lesson probably won't be called `data-cleanup`.

9.  Manually add the lesson template repository as a remote called `template`:

    ~~~

    $ git remote add template git@github.com:swcarpentry/lesson-template.git

    $ git remote add template https://github.com/swcarpentry/lesson-template.git

    ~~~

    This will allow you to pull in changes made to the template,

    such as improvements to our CSS style files.

    (Note that the user name above is `swcarpentry`, *not* `gvwilson`,

    since you are adding the master copy of the template as a remote.)

10. Create and edit files as explained in

    [Lesson Layout](LAYOUT.md),

    $ git push origin gh-pages

    ~~~

13. Tell us where your lesson is so that we can add it to

13. [Tell us](#getting-and-giving-help) where your lesson is so that we can add it to

    [the Software Carpentry lessons page][swc-lessons-page].

**Note:** SSH cloning (rather than the HTTPS cloning used above)

will also work for those who have set up SSH keys with GitHub.

**Note:** Once a lesson has been created, please submit changes

for review as pull requests that contain _only the modified Markdown files_,

and _not_ the re-generated HTML.  This simplifies review considerably,

for review as pull requests that contain *only the modified Markdown files*,

and *not* the re-generated HTML.  This simplifies review considerably,

since each change appears only once.  Once the change has been approved,

the lesson maintainer(s) will re-generate the HTML and merge it.

the lesson maintainer(s) will merge the pull request, re-generate the HTML

locally, and pus that to GitHub.

**Note:**

some people have had intermittent errors during the import process,

possibly because of the network timing out.

If you experience a problem, please re-try;

if the problem persists,

please [get in touch](#getting-and-giving-help).

## Dependencies

## Why Is This Example (and Documentation) Separate from the Template?

We want it to be easy for authors to merge changes to

the [lesson template][swc-lesson-template]

We want it to be easy for authors to merge changes

made to the [lesson template][swc-lesson-template]

into their lesson.

If the lesson template contained all of the documentation in this example,

then every time a merge was done,

(Note that from Fall 2014 to Spring 2015 we tried using two branches in a single repository,

one for the core files and one for the example.

Many contributors found it confusing;

Many contributors [found it confusing](https://github.com/swcarpentry/lesson-template/issues/118);

we hope that separate repositories will be easier to keep straight.)

## Lesson Structure

## Getting and Giving Help

We are committed to offering a pleasant setup experience for our learners and organizers.

If you find bugs in our instructions,

or would like to suggest improvements,

please [file an issue](https://github.com/swcarpentry/lesson-template/issues)

or [mail us](mailto:admin@software-carpentry.org).

please [file an issue in this repository](https://github.com/swcarpentry/lesson-example/issues);

if you find bugs in the template files themselves,

please [file an issue in the `lesson-template` repository](https://github.com/swcarpentry/lesson-template/issues).

You can also [mail us](mailto:admin@software-carpentry.org) with questions or problems.

Please also [mail us](mailto:admin@software-carpentry.org)

whenever you create a new lesson and would like to advertise it on our web site.

[swc]: http://software-carpentry.org

[swc-lesson-template]: https://github.com/swcarpentry/lesson-template

## The Problem

- Surveyed 1972 scientists in 2008.

- “How do you use computers?”

- “How did you learn what you know?”

- "How do you use computers?"

- "How did you learn what you know?"

## The Problem

## The Problem

- No hard data on how *well* they do things.

- But anecdotal evidence suggests “not very”.

- But anecdotal evidence suggests "not very".

## Our Solution