diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 69b089c..e2c2509 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,37 +4,71 @@ Contributions are very welcome.
 Please file issues or submit pull requests in [our GitHub repository][repo].
 All contributors will be acknowledged.
 
-## In Brief
+## Setup
 
 -   Use `pip install -r requirements.txt`
     to install the packages required by the helper tools and Python examples.
     You may wish to create a new virtual environment before doing so.
     All code has been tested with Python 3.12.1.
 
--   Content lives in the `.md` files under the `src` directory
-    and is translated into a static website using [Ark][ark].
-    Each page must be in its own sub-directory except for `src/index.md`,
-    which becomes the site's home page.
+-   Run `make` without arguments to see available commands
+    Of these,
+    `make build` to rebuild everything in `./docs`
+    and `make serve` to run a local preview server
+    are the most immediately useful.
 
--   `Makefile` references `lib/mccole/mccole.mk`;
-    typing `make` by itself on the command line will list available targets.
+| Command      | Action |
+| ------------ | ------ |
+| `commands`   | show available commands |
+| `build`      | rebuild site without running server |
+| `serve`      | build site and run server |
+| `profile`    | profile compilation |
+| `bib`        | rebuild HTML version of bibliography |
+| `lint`       | check project |
+| `style`      | check Python code style |
+| `reformat`   | reformat unstylish Python code |
+| `pack`       | create a release |
+| `unpack`     | make required files after unzipping mccole.zip |
+| `clean`      | clean up stray files |
 
--   All external links are written using `[box][notation]` inline
-    and defined in `info/tutorial.yml`.
+## Layout
+
+-   This template uses [Ark][ark] to compile Markdown with embedded shortcode directives
+    into a static HTML site under `docs/`.
+
+-   The McCole theme lives in `lib/mccole`:
+    -   `bin/`: utility scripts
+    -   `colophon.yml`: links used in the colophon
+    -   `extensions/`: shortcodes and other extensions to Ark used by the theme
+    -   `mccole.mk`: targets and commands common to all projects that use this theme
+    -   `requirements.txt`: packages common to all projects that use this theme
+    -   `resources/`: CSS files and other resources used by this theme
+    -   `templates/`: HTML templates used by this theme (the main one being `node.ibis`).
+
+-   The site's configuration lives in `config.py`.
+    The lists `chapters` and `appendices` define slugs for the sections, in order.
+
+-   Content lives in `.md` files in subdirectories under `src`
+    Each section must be in its own subdirectory except for `src/index.md`,
+    which is the site's home page.
+
+-   Please write external links using `[box][notation]`
+    and define links in `info/tutorial.yml`
+    rather than putting links inline.
+    Doing this will help ensure consistency across pages.
 
 -   Use `[%x slug %]` to create a cross-reference to a chapter or appendix,
-    where the slug is the name of a sub-directory under `src`.
+    where the slug is the name of a subdirectory under `src`.
 
 -   Use `[%g key "text" %]` to link to glossary entries.
     The text is inserted and highlighted;
     the key must identify an entry in `info/glossary.yml`,
     which is in [Glosario][glosario] format.
 
--   Use `[%b key1 key2 %]` to cite bibliography entries,
-    which are stored in BibTeX format in `info/bibliography.bib`.
-
--   Use `[%inc filename %]` to include a text file containing code or sample output
-    in a Markdown file.
+-   Use `[%b key1 key2 %]` to cite bibliography entries.
+    The keys must appear in `info/bibliography.bib`,
+    which is stored in BibTeX format
+    and compiled to create `tmp/bibliography.html`.
 
 -   Use `[%figure slug="some_slug" img="some_file.ext" caption="the caption" alt="alt text" %]`
     to create a figure and `[%f some_slug %]` to refer to it.
@@ -42,6 +76,11 @@ All contributors will be acknowledged.
 -   Use `[%table slug="some_slug" tbl="some_file.tbl" caption="the caption" %]`
     to create a table and `[%g some_slug %]` to refer to it.
 
+-   Use `[%inc filename %]` to include a text file containing code or sample output
+    in a Markdown file.
+    If the inclusion contains `mark=label`
+    then only code between comments marked `[label]` and `[/label]` will be included.
+
 -   SVG diagrams can be edited using [draw.io][draw_io].
     Please use 14-point Helvetica for text,
     solid 1-point black lines,
@@ -49,7 +88,60 @@ All contributors will be acknowledged.
 
 ## FAQ
 
+What is this for?
+:   I wrote [a short SQL tutorial][sql] in 2024,
+    and am currently working on one about [systems programming][sys]
+    and another about [research software design][rsdx].
+    I was initially going to use the template I built for
+    the [JavaScript][sdxjs] and [Python][sdxpy] versions of *Software Design by Example*,
+    but realized I could slim it down,
+    speed it up,
+    and make it prettier.
+    Some people knit
+    some play video games,
+    I like to type…
+
+Why Ark?
+:   [Jekyll][jekyll] is the default for [GitHub Pages][ghp],
+    but very few data scientists use Ruby
+    so previewing changes locally would require them to install and use
+    yet another language framework.
+    In addition,
+    GitHub Pages doesn't allow arbitrary extensions for security reasons,
+    so the only way to implement things like bibliography citations and glossary references
+    is to use its (rather verbose) inclusions and (rather clumsy) scripting features.
+
+Why Make?
+:   It runs everywhere,
+    no other build tool is a clear successor,
+    and,
+    like Jekyll,
+    it's uncomfortable enough to use that people won't be tempted to fiddle with it
+    when they could be writing content.
+
+Why hand-drawn figures rather than [Graphviz][graphviz] or [Mermaid][mermaid]?
+:   Because it's faster to Just Effing Draw than it is
+    to try to tweak layout parameters for text-to-diagram systems.
+    If you really want to make developers' lives better,
+    build a diff-and-merge tool for SVG:
+    programmers shouldn't have to use punchard-compatible data formats in the 21st Century
+    just to get the benefits of version control.
+
+Why McCole?
+:   Because it was my father's middle name.
+    He was my high school English teacher for five years (it was a small town),
+    and I learned most of what I know about writing from him.
+
 [ark]: https://www.dmulholl.com/docs/ark/main/
 [draw_io]: https://www.drawio.com/
+[ghp]: https://pages.github.com/
 [glosario]: https://glosario.carpentries.org/
+[graphviz]: https://graphviz.org/
+[jekyll]: https://jekyllrb.com/
+[mermaid]: https://mermaid.js.org/
 [repo]: https://github.com/gvwilson/mccole/
+[rsdx]: https://gvwilson.github.io/rsdx/
+[sdxjs]: https://third-bit.com/sdxjs/
+[sdxpy]: https://third-bit.com/sdxpy/
+[sql]: https://gvwilson.github.io/sql-tutorial/
+[sys]: https://gvwilson.github.io/sql-tutorial/
diff --git a/docs/contrib/index.html b/docs/contrib/index.html
index 3ffa117..b612c4a 100644
--- a/docs/contrib/index.html
+++ b/docs/contrib/index.html
@@ -51,7 +51,7 @@ <h1>Contributing</h1>
       <p>Contributions are very welcome.
 Please file issues or submit pull requests in <a href="https://github.com/gvwilson/mccole/">our GitHub repository</a>.
 All contributors will be acknowledged.</p>
-<h2>In Brief</h2>
+<h2>Setup</h2>
 <ul>
 <li>
 <p>Use <code>pip install -r requirements.txt</code>
@@ -60,22 +60,103 @@ <h2>In Brief</h2>
     All code has been tested with Python 3.12.1.</p>
 </li>
 <li>
-<p>Content lives in the <code>.md</code> files under the <code>src</code> directory
-    and is translated into a static website using <a href="https://www.dmulholl.com/docs/ark/main/">Ark</a>.
-    Each page must be in its own sub-directory except for <code>src/index.md</code>,
-    which becomes the site&rsquo;s home page.</p>
+<p>Run <code>make</code> without arguments to see available commands
+    Of these,
+    <code>make build</code> to rebuild everything in <code>./docs</code>
+    and <code>make serve</code> to run a local preview server
+    are the most immediately useful.</p>
+</li>
+</ul>
+<table>
+<thead>
+<tr>
+<th>Command</th>
+<th>Action</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>commands</code></td>
+<td>show available commands</td>
+</tr>
+<tr>
+<td><code>build</code></td>
+<td>rebuild site without running server</td>
+</tr>
+<tr>
+<td><code>serve</code></td>
+<td>build site and run server</td>
+</tr>
+<tr>
+<td><code>profile</code></td>
+<td>profile compilation</td>
+</tr>
+<tr>
+<td><code>bib</code></td>
+<td>rebuild HTML version of bibliography</td>
+</tr>
+<tr>
+<td><code>lint</code></td>
+<td>check project</td>
+</tr>
+<tr>
+<td><code>style</code></td>
+<td>check Python code style</td>
+</tr>
+<tr>
+<td><code>reformat</code></td>
+<td>reformat unstylish Python code</td>
+</tr>
+<tr>
+<td><code>pack</code></td>
+<td>create a release</td>
+</tr>
+<tr>
+<td><code>unpack</code></td>
+<td>make required files after unzipping mccole.zip</td>
+</tr>
+<tr>
+<td><code>clean</code></td>
+<td>clean up stray files</td>
+</tr>
+</tbody>
+</table>
+<h2>Layout</h2>
+<ul>
+<li>
+<p>This template uses <a href="https://www.dmulholl.com/docs/ark/main/">Ark</a> to compile Markdown with embedded shortcode directives
+    into a static HTML site under <code>docs/</code>.</p>
+</li>
+<li>
+<p>The McCole theme lives in <code>lib/mccole</code>:</p>
+<ul>
+<li><code>bin/</code>: utility scripts</li>
+<li><code>colophon.yml</code>: links used in the colophon</li>
+<li><code>extensions/</code>: shortcodes and other extensions to Ark used by the theme</li>
+<li><code>mccole.mk</code>: targets and commands common to all projects that use this theme</li>
+<li><code>requirements.txt</code>: packages common to all projects that use this theme</li>
+<li><code>resources/</code>: CSS files and other resources used by this theme</li>
+<li><code>templates/</code>: HTML templates used by this theme (the main one being <code>node.ibis</code>).</li>
+</ul>
 </li>
 <li>
-<p><code>Makefile</code> references <code>lib/mccole/mccole.mk</code>;
-    typing <code>make</code> by itself on the command line will list available targets.</p>
+<p>The site&rsquo;s configuration lives in <code>config.py</code>.
+    The lists <code>chapters</code> and <code>appendices</code> define slugs for the sections, in order.</p>
 </li>
 <li>
-<p>All external links are written using <code>[box][notation]</code> inline
-    and defined in <code>info/tutorial.yml</code>.</p>
+<p>Content lives in <code>.md</code> files in subdirectories under <code>src</code>
+    Each section must be in its own subdirectory except for <code>src/index.md</code>,
+    which is the site&rsquo;s home page.</p>
+</li>
+<li>
+<p>Please write external links using <code>[box][notation]</code>
+    and define links in <code>info/tutorial.yml</code>
+    rather than putting links inline.
+    Doing this will help ensure consistency across pages.</p>
 </li>
 <li>
 <p>Use <code>[%x slug %]</code> to create a cross-reference to a chapter or appendix,
-    where the slug is the name of a sub-directory under <code>src</code>.</p>
+    where the slug is the name of a subdirectory under <code>src</code>.</p>
 </li>
 <li>
 <p>Use <code>[%g key "text" %]</code> to link to glossary entries.
@@ -84,12 +165,10 @@ <h2>In Brief</h2>
     which is in <a href="https://glosario.carpentries.org/">Glosario</a> format.</p>
 </li>
 <li>
-<p>Use <code>[%b key1 key2 %]</code> to cite bibliography entries,
-    which are stored in BibTeX format in <code>info/bibliography.bib</code>.</p>
-</li>
-<li>
-<p>Use <code>[%inc filename %]</code> to include a text file containing code or sample output
-    in a Markdown file.</p>
+<p>Use <code>[%b key1 key2 %]</code> to cite bibliography entries.
+    The keys must appear in <code>info/bibliography.bib</code>,
+    which is stored in BibTeX format
+    and compiled to create <code>tmp/bibliography.html</code>.</p>
 </li>
 <li>
 <p>Use <code>[%figure slug="some_slug" img="some_file.ext" caption="the caption" alt="alt text" %]</code>
@@ -100,6 +179,12 @@ <h2>In Brief</h2>
     to create a table and <code>[%g some_slug %]</code> to refer to it.</p>
 </li>
 <li>
+<p>Use <code>[%inc filename %]</code> to include a text file containing code or sample output
+    in a Markdown file.
+    If the inclusion contains <code>mark=label</code>
+    then only code between comments marked <code>[label]</code> and <code>[/label]</code> will be included.</p>
+</li>
+<li>
 <p>SVG diagrams can be edited using <a href="https://www.drawio.com/">draw.io</a>.
     Please use 14-point Helvetica for text,
     solid 1-point black lines,
@@ -107,6 +192,47 @@ <h2>In Brief</h2>
 </li>
 </ul>
 <h2>FAQ</h2>
+<dl>
+<dt>What is this for?</dt>
+<dd>I wrote <a href="https://gvwilson.github.io/sql-tutorial/">a short SQL tutorial</a> in 2024,
+and am currently working on one about <a href="https://gvwilson.github.io/sql-tutorial/">systems programming</a>
+and another about <a href="https://gvwilson.github.io/rsdx/">research software design</a>.
+I was initially going to use the template I built for
+the <a href="https://third-bit.com/sdxjs/">JavaScript</a> and <a href="https://third-bit.com/sdxpy/">Python</a> versions of <em>Software Design by Example</em>,
+but realized I could slim it down,
+speed it up,
+and make it prettier.
+Some people knit
+some play video games,
+I like to type…</dd>
+<dt>Why Ark?</dt>
+<dd><a href="https://jekyllrb.com/">Jekyll</a> is the default for <a href="https://pages.github.com/">GitHub Pages</a>,
+but very few data scientists use Ruby
+so previewing changes locally would require them to install and use
+yet another language framework.
+In addition,
+GitHub Pages doesn&rsquo;t allow arbitrary extensions for security reasons,
+so the only way to implement things like bibliography citations and glossary references
+is to use its (rather verbose) inclusions and (rather clumsy) scripting features.</dd>
+<dt>Why Make?</dt>
+<dd>It runs everywhere,
+no other build tool is a clear successor,
+and,
+like Jekyll,
+it&rsquo;s uncomfortable enough to use that people won&rsquo;t be tempted to fiddle with it
+when they could be writing content.</dd>
+<dt>Why hand-drawn figures rather than <a href="https://graphviz.org/">Graphviz</a> or <a href="https://mermaid.js.org/">Mermaid</a>?</dt>
+<dd>Because it&rsquo;s faster to Just Effing Draw than it is
+to try to tweak layout parameters for text-to-diagram systems.
+If you really want to make developers&rsquo; lives better,
+build a diff-and-merge tool for SVG:
+programmers shouldn&rsquo;t have to use punchard-compatible data formats in the 21st Century
+just to get the benefits of version control.</dd>
+<dt>Why McCole?</dt>
+<dd>Because it was my father&rsquo;s middle name.
+He was my high school English teacher for five years (it was a small town),
+and I learned most of what I know about writing from him.</dd>
+</dl>
     </main>
     <footer>
   © 2024 <a href="https://third-bit.com/">Greg Wilson</a>