diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3fa1e34ef310c1364ff02f6cd5b2b438f6dbe159..f9ab2df7dd12cc12cf08f718cd42dc045eba2fa4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,18 +13,22 @@ You also agree to abide by our
## 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
diff --git a/FAQ.md b/FAQ.md
index 580b2a1aa70787de8f885b17b535233b0869c6f5..60e6b660cfa67def3bf457c98fb0e47806b6e164 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -12,7 +12,7 @@
[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.
diff --git a/LAYOUT.md b/LAYOUT.md
index c7f946b5023b49564982790f0882c0e8aa3b17f2..e2b1ec96a628bc429e74af873cc0000e5d271015 100644
--- a/LAYOUT.md
+++ b/LAYOUT.md
@@ -10,7 +10,7 @@ submodules or clever tricks with symbolic links).
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.
~~~
@@ -336,41 +336,40 @@ random number generation is outside the scope of the lesson,
## 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).
@@ -395,29 +394,36 @@ a definition list:
## 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
@@ -471,3 +477,5 @@ interleaved in the lesson itself. Its structure is:
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
diff --git a/README.md b/README.md
index 1cf61b3421db27a6fe9cbfda37e54f21bfa135bf..4b4d9402f878271f3c0d1541e746510f101a1ff4 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,85 @@
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:
+
+ 
+
+ 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
@@ -50,22 +90,37 @@ lesson is `data-cleanup`.
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
@@ -112,6 +167,26 @@ We organize our lessons in a standard way so that:
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:
@@ -159,16 +234,19 @@ Please see the following for more information on:
* [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
diff --git a/img/using-github-import.png b/img/using-github-import.png
new file mode 100644
index 0000000000000000000000000000000000000000..355561122cf3f3ce0693e18f197586dce231e86a
Binary files /dev/null and b/img/using-github-import.png differ
diff --git a/motivation.html b/motivation.html
index 029812d9465f0ba9869f18ac04a2bd1208c0d239..133554888476d6c3639f0df6681271f3e53a4502 100644
--- a/motivation.html
+++ b/motivation.html
@@ -35,8 +35,8 @@
<h1>The Problem</h1>
<ul>
<li>Surveyed 1972 scientists in 2008.</li>
-<li>“How do you use computers?”</li>
-<li>“How did you learn what you know?”</li>
+<li>"How do you use computers?"</li>
+<li>"How did you learn what you know?"</li>
</ul>
</section>
<section id="the-problem-1" class="slide level2">
@@ -51,7 +51,7 @@
<h1>The Problem</h1>
<ul>
<li>No hard data on how <em>well</em> they do things.</li>
-<li>But anecdotal evidence suggests “not very”.</li>
+<li>But anecdotal evidence suggests "not very".</li>
</ul>
</section>
<section id="our-solution" class="slide level2">
diff --git a/motivation.md b/motivation.md
index 3ffcd0efa028ec006b28df92a5cafcc9c2d1d998..5b1a065a79e7e1ad15f3da49d7dc6fe34bc6721c 100644
--- a/motivation.md
+++ b/motivation.md
@@ -11,8 +11,8 @@ We make scientists and engineering more productive by teaching them basic comput
## 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
@@ -25,7 +25,7 @@ We make scientists and engineering more productive by teaching them basic comput
## 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