Explaining tooling

_config.yml

@@ -22,10 +22,11 @@ email: gvwilson@software-carpentry.org
 #------------------------------------------------------------
 
 # Sites.
-amy_site:   "https://amy.software-carpentry.org/workshops"
-dc_site:    "https://datacarpentry.org"
+amy_site: "https://amy.software-carpentry.org/workshops"
+dc_site: "https://datacarpentry.org"
 swc_github: "https://github.com/swcarpentry"
-swc_site:   "https://software-carpentry.org"
+swc_site: "https://software-carpentry.org"
+template_repo: "https://github.com/gvwilson/new-lesson-template"
 
 # Start time in minutes (540 is 09:00 am)
 start_time: 540

_episodes/01-tooling.md

@@ -10,53 +10,67 @@ objectives:
 keypoints:
 - "FIXME"
 ---
+This episode describes tools we use to manage lessons,
+which simplify many tasks but make other things more complicated.
+
 ## Repositores on GitHub
 
-Git uses the term *clone* to mean "a copy of a repository".
-GitHub uses the term *fork* to mean, "a copy of a GitHub-hosted
-repo that is also hosted on GitHub", and the term *clone* to mean
-"a copy of a GitHub-hosted repo that's located on someone else's
-machine".  In both cases, the duplicate has a remote called
-`origin` that points to the original repo; other remotes can be
-added manually.
+All of our lessons are stored in Git repositories on GitHub.
+Git uses the term *clone* to mean "a copy of a repository",
+while GitHub uses the term *fork* to mean "a copy of a GitHub-hosted repo that is also hosted on GitHub"
+and the term *clone* to mean "a copy of a GitHub-hosted repo that's located on someone else's machine".
+In both cases,
+the duplicate has a remote called `origin` that points to the original repo;
+other remotes can be added manually.
 
 A user on GitHub can only have one fork of a particular repo.
-This is a problem for us because an author may be involved in
-writing several lessons, each of which has its own website repo.
-Those website repositories ought to be forks of this one, but
-since GitHub doesn't allow that, we've had to find a workaround.
+This is a problem for us because an author may be involved in writing several lessons,
+each of which has its own website repo.
+Those website repositories ought to be forks of the [template repository]({{ site.template_repo }}),
+but since GitHub doesn't allow that,
+we use [GitHub Importer][github-importer] when creating new lessons.
+After the lesson has been created,
+we manually add the [template repository]({{ site.template_repo }}) as a remote called `template`
+to update the lesson when the template changes.
 
 ## GitHub Pages
 
-If a repository has a branch called `gh-pages` (which stands for
-"GitHub pages"), then GitHub uses the HTML and Markdown files in
-that branch to create a website for the repository.  If the
-repository's URL is `http://github.com/darwin/finches`, the URL
-for the website is `http://darwin.github.io/finches`.
+If a repository has a branch called `gh-pages` (short for "GitHub Pages"),
+GitHub publishes its content to create a website for the repository.
+If the repository's URL is `https://github.com/USERNAME/REPOSITORY`,
+the website is `https://USERNAME.github.io/REPOSITORY`.
+
+Websites can be static HTML pages,
+which are published as-is,
+or can use the [Jekyll][jekyll] templating system described below.
 
 ## Markdown
 
-We use Markdown for writing pages because it's simple to learn,
-and isn't tied to any specific language (the ReStructured Text
-format popular in the Python world, for example, is a complete
-unknown to R programmers).  If authors want to use something else
-to author their lessons (e.g., Jupyter Notebooks), it's up to them
-to generate and commit Markdown formatted according to the rules
-below.
+We use Markdown for lesson content because it's simple to learn
+and isn't tied to any specific language
+(the ReStructured Text format popular in the Python world,
+for example,
+is a complete unknown to R programmers).
+If authors want to use something else to author their lessons,
+such as [R Markdown][r-markdown],
+they must generate Markdown that [Jekyll][jekyll] can process,
+or static HTML,
+and commit that to the repository.
 
 > ## Tooling
 >
-> Note that we do *not* prescribe what tools instructors should use
-> when actually teaching.  The Jupyter Notebook, Python IDEs like
-> Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all
-> equally welcome up on stage --- all we specify is the format of
-> the lesson notes.
+> We do *not* prescribe what tools instructors should use when actually teaching:
+> the [Jupyter Notebook][jupyter],
+> [RStudio][rstudio],
+> and the good ol' command line are equally welcome up on stage.
+> All we specify is the format of the lesson notes.
 {: .callout}
 
 ## Jekyll
 
-GitHub uses Jekyll to turn Markdown into HTML.  Jekyll looks for
-a header at the top of each page formatted like this:
+GitHub uses [Jekyll][jekyll] to turn Markdown into HTML.
+By default,
+it looks for text files that begin with a header formatted like this:
 
 ~~~
 ---
@@ -67,18 +81,34 @@ other_variable: other_value
 ~~~
 {: .source}
 
-and inserts the values of those variables into the page when
-formatting this.  Lesson authors will usually not have to worry
-about this.
-
-Jekyll also takes values from a `_config.yml` configuration file
-and inserts them into the page.  Lesson authors will also not
-have to worry about this in most cases, provided they update the
-`title`, `lesson_repo`, and `lesson_site` variables in `_config.yml`.
-
-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.
+and inserts the values of those variables into the page when formatting this.
+The three dashes that start the header *must* be the first three characters in the file:
+even a single space before them will make [Jekyll][jekyll] ignore the file.
+
+Jekyll requires the header to be formatted as [YAML][yaml],
+which provides Booleans, numbers, character strings, lists, and dictionaries of name/value pairs.
+Values from the header are referred to in the page as `page.variable`.
+
+## Configuration
+
+Jekyll also reads values from a configuration file called `_config.yml`,
+which are referred to in the page as `site.variable`.
+The [lesson template]({{ site.template_repo }}) does *not* include `_config.yml`,
+since each lesson will change some of its value,
+which would result in merge collisions each time the lesson was updated from the template.
+Instead,
+the [template]({{ site.template_repo }}) contains `_config_template.yml`;
+authors should copy this file to create `_config.yml`
+and then edit values in the top half.
+
+The [template]({{ site.template_repo }}) also contains `_config_dev.yml`,
+which overrides some settings for use during desktop development.
+The Makefile that comes with the [template]({{ site.template_repo }})
+adds these values to those in `_config.yml` when running a local server.
+
+[github-importer]: https://import.github.com/
+[jekyll]: http://jekyllrb.com/
+[jupyter]: https://jupyter.org/
+[r-markdown]: http://rmarkdown.rstudio.com/
+[rstudio]: https://www.rstudio.com/
+[yaml]: http://yaml.org/

_episodes/03-organization.md

@@ -11,7 +11,12 @@ keypoints:
 ---
 ## Common Files
 
-FIXME
+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.
 
 ## Layouts