Updating documentation.

1.  Explaining how to use GitHub import instead of creating a repository manually.
2.  Explaining the difference between `lesson-template` and `lesson-example`.

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

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.
     ~~~
@@ -411,7 +411,10 @@ The discussion page
 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.
+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.
 
 ## Instructor's Guide
 
@@ -471,3 +474,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

README.md

 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 is an example of a lesson created using
+the [Software Carpentry][swc] [lesson template][swc-lesson-template].
+
+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].
+
+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/).
 
 ## Manual Setup
 
-We will assume that your user ID is `mcurie` and the name of your
+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)
 
-2.  Clone the template repository to your computer in a directory with
-    the same name as your lesson identifier:
+    You can now click "Begin Import".
+    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 -o upstream https://github.com/swcarpentry/lesson-template.git data-cleanup
+    $ git clone -b gh-pages git@github.com:gvwilson/data-cleanup.git
     ~~~
 
-3.  Go into that directory using
+8.  Go into that directory using
 
     ~~~
     $ cd data-cleanup
     ~~~
 
-4.  Add your GitHub repository as a remote called `origin` using
+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 git@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.
+
+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 +85,29 @@ 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 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 re-generate the HTML and merge it.
+
 ## Dependencies
 
 Because people may choose to use the IPython Notebook, R Markdown, or
@@ -112,6 +154,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 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;
+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:
@@ -165,10 +227,15 @@ 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.
 
-## Giving Help
+## 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?q=is%3Aopen+is%3Aissue)
+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).
+
+[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