Merge branch 'gh-pages' of github.com:swcarpentry/lesson-example into gh-pages

[How to Contribute to an Open Source Project on GitHub][how-contribute].

In brief:

1.  The published copy of the lesson is in the `gh-pages` branch of the repository

1.  The published copy of the lesson is in the [episodes][episodes] directory in the `gh-pages` branch of the repository

    (so that GitHub will regenerate it automatically).

    Please create all branches from that,

    and merge the [master repository][repo]'s `gh-pages` branch into your `gh-pages` branch

[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry

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

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

[episodes]: _episodes

Contribution guidelines.

The `issues` and `repo` links at the bottom of the file must be changed

to match the URLs of the lesson:

look for uses of `{LESSON-NAME}`.

look for uses of `FIXME`.

### `_config.yml`

The home page for the lesson.

1.  It must use the `index` layout.

1.  It must use the `lesson` layout.

2.  It must *not* have a `title` field in its [YAML][yaml] header.

3.  It must open with a few paragraphs of explanatory text.

4.  That introduction must be followed by a single `.prereq` blockquote

title: "Instructor Notes"

permalink: /guide/

---

Discussion of the lesson aimed at instructors would normally go here,

but since this is just an example,

there isn't much to say.

The instructor notes should provide additional discussion useful to instructors, 

but not appropriate for inclusion in the main lessons. The following structure 

provides a consistent way for instructors to both prepare for a workshop and 

quickly find necessary information during a workshop.

Please remember not to overload on details, and to keep the comments here positive!

## Lesson motivation and learning objectives

These concepts should be highlighted in the main lesson material, but ideas for 

explaining these concepts further can be placed here. 

## Lesson design

Most lessons contain more material than can be taught in a single workshop. 

Describe a general narrative (with time estimates) for teaching either a half day 

or full day with this lesson material. You may also choose to include multiple 

options for lesson design, or what material can be skipped while teaching. 

This section may also include recommendations for how this lesson fits into 

the overall workshop.

## Technical tips and tricks

Provide information on setting up your environment for learners to view your 

live coding (increasing text size, changing text color, etc), as well as 

general recommendations for working with coding tools to best suit the 

learning environment.

## Common problems

This can include answers to common learner questions, as well as links to 

resources (blog posts, stack overflow answers, etc) that may solve problems that 

may occur during a workshop.

## Creating a New Lesson

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

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

lesson is `data-cleanup`.

1.  Go to [GitHub's importer][importer].

    Do *not* use the URL of this repository,

    as that will bring in a lot of example files you don't actually want.

3.  Click on "Check the URL".  (GitHub won't import until you've done this.)

4.  Select the owner for your new repository.

    In our example this is `gvwilson`,

3.  Select the owner for your new repository.

    In our example this is `timtomch`,

    but it may instead be an organization you belong to.

5.  Choose a name for your lesson repository.

4.  Choose a name for your lesson repository.

    In our example, this is `data-cleanup`.

6.  Make sure the repository is public.

5.  Make sure the repository is public.

7.  At this point, you should have a page like this:

6.  At this point, you should have a page like this:

    ![]({{ page.root }}/fig/using-github-import.png)

    When the process is done,

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

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

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

    ~~~

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

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

    ~~~

    {: .source}

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

9.  Go into that directory using:

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

10. Manually add the styles repository as a remote called `template`:

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

    ~~~

    $ git remote add template https://github.com/swcarpentry/styles.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`,

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

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

10. Make sure you are using the `gh-pages` branch of the lesson template:

    ~~~

    $ git checkout gh-pages

    ~~~

    {: .source}

	This will ensure that you are using the most "stable" version of the

	template repository. Since it's being actively maintained by the

	Software Carpentry community, you could end up using a development branch

	that contains experimental (and potentially not working) features without

	necessarily realising it. Switching to the `gh-branch` ensures you are

	using the "stable" version of the template.

11. Run `bin/lesson_initialize.py` to create all of the boilerplate files

    that cannot be put into the styles repository

    (because they would trigger repeated merge conflicts).