Merge pull request #1 from gvwilson/updating-docs

## Getting Started

1.  We use GitHub flow to manage changes,

1.  Please see [the README](README.html#getting-and-giving-help)

    for advice on getting and giving help.

2.  We use GitHub flow to manage changes,

    which is explained in the chapter [Contributing to a Project][pro-git-chapter]

    in Scott Chacon's book *Pro Git*.

2.  For our lessons,

3.  For our lessons,

    you should branch from and submit pull requests against the `gh-pages` branch.

3.  When editing lesson pages, you need only commit changes to the Markdown source files.

4.  When editing lesson pages, you need only commit changes to the Markdown source files.

4.  If you're looking for things to work on,

    please see [the list of issues for this repository][lesson-template-issues],

    or for [our other lessons][swc-lessons].

5.  If you're looking for things to work on,

    please see [the list of issues for this repository][lesson-example-issues]

    or for [the template][lesson-template-issues],

    or have a look at [our actual lessons][swc-lessons].

    Comments on issues and reviews of pull requests are equally welcome.

## Other Resources

    [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 from scratch? 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.

    instructions:

    ~~~

    > Please see [https://github.com/swcarpentry/lesson-template](https://github.com/swcarpentry/lesson-template)

    > Please see [https://github.com/swcarpentry/lesson-example][swc-lesson-example]

    > for instructions on formatting, building, and submitting lessons,

    > or run `make` in this directory for a list of helpful commands.

    ~~~

## 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

        This may span several paragraphs.

    Paragraphs of general discussion

    *   Second point of general discussion.

    ## Something Else

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.

    More general discussion, with links.

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

    mention how long it typically takes to do.  (Those estimates do

    not go in the challenge itself, since they can increase learners'

    stress levels.)

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

lesson-example

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

This repository is an example of a [Software Carpentry](http://software-carpentry.org) lesson

created using the [lesson template](https://github.com/swcarpentry/lesson-template).

Do *not* fork this repository directly on GitHub.

Instead, follow the instructions below to create a lesson repository

from the [lesson template](https://github.com/swcarpentry/lesson-template),

then go through [the layout instructions](LAYOUT.md) to create a lesson.

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.

## Manual Setup

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

    Instead, please follow the instructions below

    to create a repository for your lesson from

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

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

2.  Once you have created the repository,

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

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.

## Creating Your Lesson's Repository

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

lesson is `data-cleanup`.

1.  Create an empty repository on GitHub called `data-cleanup`.

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

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

3.  Select the owner for your new repository.

    In our example this is `gvwilson`,

    but it may instead be an organization you belong to.

4.  Choose a name for your lesson repository.

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

5.  Make sure the repository is public.

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

    ![](img/using-github-import.png)

    You can now click "Begin Import".

    When the process is done,

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

2.  Clone the template repository to your computer in a directory with

    the same name as your lesson identifier:

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

    ~~~

    $ git clone -b gh-pages -o upstream https://github.com/swcarpentry/lesson-template.git data-cleanup

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

    ~~~

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

    ~~~

4.  Add your GitHub repository as a remote called `origin` using

    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 origin https://github.com/mcurie/data-cleanup

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

    ~~~

5.  Create and edit files as explained in

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

    [Background and Design](DESIGN.md),

    and the [FAQ](FAQ.md).

6.  Build the HTML pages for your lesson:

11. Build the HTML pages for your lesson:

    ~~~

    $ make preview

    lesson yourself and push them to GitHub, rather than relying on

    GitHub to build them for you.

7.  Commit your changes *and the HTML pages in the root directory of

12. Commit your changes *and the HTML pages in the root directory of

    your lesson repository* and push to the `gh-pages` branch of your

    repository:

    ~~~

    $ cd data-cleanup

    $ git add changed-files.md *.html

    $ git add changed-file.md changed-file.html

    $ git commit -m "Explanatory message"

    $ git push origin gh-pages

    ~~~

8.  Tell us where your lesson is so that we can use it and help you improve it.

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 that SSH cloning (as opposed to the HTTPS cloning used above)

**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,

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

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

Because people may choose to use the IPython Notebook, R Markdown, or

5.  Content can be checked mechanically.

## Why Is This Example and Documentation Separate from the 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,

authors would have to re-delete those files,

undo merges into their lesson's `README.md`,

etc.

We hope that putting the core files in a repository of their own

will avoid this problem.

(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](https://github.com/swcarpentry/lesson-template/issues/118);

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

## Lesson Structure

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:

*   [background and design](DESIGN.md)

*   [FAQ](FAQ.md)

## Getting Help

## Getting and Giving Help

Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org),

or join our [discussion list](http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org)

and ask for help there.

If you find bugs in our instructions,

or would like to suggest improvements,

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.

## Giving Help

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.

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?q=is%3Aopen+is%3Aissue)

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

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

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

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

[import]: http://import.github.com/new?import_url=https://github.com/swcarpentry/lesson-template