Stock files

_episodes/03-organization.md

@@ -9,23 +9,53 @@ objectives:
 keypoints:
 - "FIXME"
 ---
-## Common Files
+Our lessons need artwork,
+CSS style files,
+and a few bits of Javascript.
+We could load these from the web,
+but that would make offline authoring difficult.
+Instead, each lesson's repository is self-contained.
+
+Note: files that appear as top-level items in the navigation menu are stored in the root directory.
+Files that appear under the "extras" menu are stored in the `_extras` directory
+(which is turned into a [Jekyll collection][jekyll-collection] for easier processing).
+
+## Standard Files
+
+The [lesson template]({{ site.template_repo }}) provides the following files
+which should *not* be modified:
 
-In order to display properly, our generated HTML pages need artwork,
-CSS style files, and a few bits of Javascript.  We could load these
-from the web, but that would make offline authoring difficult.
-Instead, each lesson's repository is self-contained and has a copy of
-all these third party resources, and a way of updating them (and only
-them) on demand.
+*   `CONDUCT.md`: the code of conduct.
+*   `LICENSE.md`: the lesson license.
+*   `Makefile`: commands for previewing the site, cleaning up junk, etc.
+*   `_extras/contributing.md`: contribution guidelines.
 
-## Layouts
+Run `make` on its own to get a list of targets in the Makefile.
 
-FIXME
+## Common Files
+
+Most lessons will contain the following files which are *not* in the template
+(to avoid repeated merge conflicts):
 
-## Inclusions
+*   `AUTHORS`: names and email addresses of authors.
+*   `CITATION`: how the lesson should be cited in publications.
+*   `README.md`: brief description of the lesson displayed by GitHub.
+*   `index.md`: the home page for the lesson (discussed below).
+*   `reference.md`: a reference guide for the lesson (discussed below).
+*   `setup.md`: setup instructions for the lesson (discussed below).
+*   `_extras/discussion.md`: general discussion.
+*   `_extras/guide.md`: the instructors' guide.
 
-FIXME
+## Layouts and Inclusions
+
+Page layouts are stored in `_layouts`,
+while snippets of HTML included by these layouts are stored in `_includes`,
+because that's what [Jekyll][jekyll] requires.
 
 ## Assets
 
-FIXME
+The `assets` directory contains the CSS, Javascript, fonts, and image files
+used in the generated website.
+
+[jekyll]: http://jekyllrb.com/
+[jekyll-collection]: https://jekyllrb.com/docs/collections/

reference.md

+---
+layout: reference
+title: Reference
+permalink: /reference/
+---
+FIXME: reference guide.

setup.md

+---
+layout: page
+title: Setup
+permalink: /setup/
+---
+FIXME: setup instructions.