diff --git a/FAQ.md b/FAQ.md
index 33da082236e4668d2e90631b9c98a699cd4b423c..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 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.
diff --git a/LAYOUT.md b/LAYOUT.md
index 9ab3c9f00a9cfe70b9073ff08fc47f3648347670..e2b1ec96a628bc429e74af873cc0000e5d271015 100644
--- a/LAYOUT.md
+++ b/LAYOUT.md
@@ -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
---
-
+ ## Our Mission
-
+ 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,32 +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
+
+ 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
diff --git a/README.md b/README.md
index 9e75b1b84b16dc7532909f39ae4f1fc308fc8d60..444cef8e8ede1c02b877fe281fe61b5fa7d5bb06 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
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
@@ -12,10 +13,14 @@ the [Software Carpentry][swc] [lesson template][swc-lesson-template].
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`.
@@ -41,33 +46,33 @@ 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),
@@ -96,17 +101,25 @@ please [get in touch](#getting-and-giving-help).
$ 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
@@ -156,8 +169,8 @@ We organize our lessons in a standard way so that:
## 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,
@@ -169,7 +182,7 @@ 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;
+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
@@ -229,11 +242,15 @@ and ask for help there.
## 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
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