diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ff3e4a76a..7ed607c96 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,8 +19,9 @@ to get feedback on your ideas and coordinate with other developers.
**Table of Contents**
-* [Working With GitHub](#working-with-github)
-* [Locations and Formats](#locations-and-formats)
+* [Working With GitHub](#working-with-github)
+* [Locations](#locations)
+* [Formats](#formats)
* [Sample Files](#sample-files)
* [Previewing](#previewing)
* [FAQ](#faq)
@@ -28,6 +29,15 @@ to get feedback on your ideas and coordinate with other developers.
Working With GitHub
-------------------
+In general, we are using Git and GitHub for almost everything.
+But if it is easier for you to send your contributions to us some other way,
+please mail us at
+[admin@software-carpentry.org](mailto:admin@software-carpentry.org).
+Given a choice between you creating content or wrestling with Git,
+we'd rather have you doing the former.
+
+The GitHub workflow looks like this:
+
1. Fork the `swcarpentry/bc` repository on GitHub.
2. Clone that repository to your own machine.
@@ -41,14 +51,8 @@ Working With GitHub
5. Send a pull request to the `master` branch of `[swcarpentry/bc](http://github.com/swcarpentry/bc)`.
-If it is easier for you to send them to us some other way,
-please mail us at
-[admin@software-carpentry.org](mailto:admin@software-carpentry.org).
-Given a choice between you creating content or wrestling with Git,
-we'd rather have you doing the former.
-
-Locations and Formats
----------------------
+Locations
+---------
Every subject has a sub-directory of its own,
while individual topics are files in that directory.
@@ -61,25 +65,30 @@ and so on.
(We use two digits followed by a one-word topic key
to ensure files appear in the right order when listed.)
-Lessons may be written in Markdown,
-as IPython Notebooks,
-or in other formats.
-However,
-as explained in [the README file](README.md),
-Jekyll (the tool GitHub uses to create websites)
-only knows how to handle Markdown and HTML.
-if some other format is used,
-the author of the lesson must
-add the generated Markdown to the repository.
-This ensures that people who *aren't* familiar with some format
-don't have to install the tools needed to work with it
-(e.g.,
-R programmers don't have to install the IPython Notebook).
-
-> If a lesson is in a format we don't already handle,
-> the author must also add something to the Makefile
-> to re-create the Markdown from the source.
-> Please check with us if you plan to do this.
+Formats
+-------
+
+We are using [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
+to convert lessons in [Markdown](https://en.wikipedia.org/wiki/Markdown)
+to [HTML](https://en.wikipedia.org/wiki/HTML).
+Therefore, we require every lesson to be available in Markdown.
+But this does not mean that you have to write it in Markdown as well.
+
+The following list contains more detailed instructions for different formats:
+
+* Markdown: Nothing to do.
+* IPython Notebook: Generate and provide a Markdown version in addition
+ to the IPython Notebook.
+ Look at our existing files to get an idea how the IPython Notebook
+ should look like.
+* Other formats: Generate and provide a Markdown version in addition
+ to the file in the original format.
+ In order to be able to recreate the Markdown from source,
+ include the conversion from this other format to Markdown
+ in the `Makefile` as well. This ensures that people who *aren't* familiar
+ with some format don't have to install the tools needed to work with it
+ (e.g., R programmers don't have to install the IPython Notebook).
+ **Please check with us if you plan to do this.**
Sample Files
------------
@@ -104,7 +113,7 @@ run the command `make site`.
This runs Jekyll with the same flags that GitHub uses when things are committed to the `gh-pages` branch.
Jekyll's output is stored in a directory called `_site`.
-Other useful commands in the main Makefile are:
+Other useful commands in the main `Makefile` are:
* `make commands` (or just `make` on its own): list available commands.
* `make check`: check that the repository's `index.html` file is properly formatted.
@@ -112,9 +121,9 @@ Other useful commands in the main Makefile are:
* `make fixme`: list uses of the word `FIXME` in source files.
The commands to convert IPython Notebooks to Markdown
-are stored in a separate Makefile called `ipynb.mk`
+are stored in a separate `Makefile` called `ipynb.mk`
to simplify maintenance
-and ensure that the main Makefile only does what Jekyll on GitHub will do.
+and ensure that the main `Makefile` only does what Jekyll on GitHub will do.
To re-do conversion of notebooks to Markdown files,
use `make ipynb`.
@@ -122,8 +131,12 @@ FAQ
---
* *Where can I get help?*
-
Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org),
come chat with us on [our IRC channel](irc://moznet/sciencelab),
or join our [discussion list](http://software-carpentry.org/pages/discuss.html)
and ask for help there.
+* *Is there a list of open issues to tackle?*
+ The [open issues for the bc repository](https://github.com/swcarpentry/bc/issues)
+ and also the [related projects](http://www.software-carpentry.org/pages/create.html#related)
+ listed on the create page are a good starting point.
+
diff --git a/README.md b/README.md
index 19b6940a6..0f364c2ca 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ The sections below explain:
* how GitHub turns a repository into a web site,
* how you can build a website for your bootcamp using this repo as a starting point,
-* what lessons we have,
+* which lessons we have,
* where they're located, and
* how to add new lessons.
@@ -32,14 +32,14 @@ You should not try to use the same repo for both purposes because:
**Table of Contents**
-* [Background](#background)
-* [Getting Started](#getting-started)
-* [Previewing the Site](#previewing-the-site)
-* [Variables](#variables)
-* [Website Content](#website-content)
-* [Lesson Material](#lesson-material)
-* [Building Things](#building-things)
-* [Site Map](#site-map)
+* [Background](#background)
+* [Getting Started](#getting-started)
+* [Previewing the Site](#previewing-the-site)
+* [Variables](#variables)
+* [Website Content](#website-content)
+* [Lesson Material](#lesson-material)
+* [Building Things](#building-things)
+* [Site Map](#site-map)
* [FAQ](#faq)
Background
@@ -93,7 +93,7 @@ rather than Git itself.
then GitHub doesn't just copy the file over verbatim.
Instead,
- it runs the file through a translator called Jekyll
+ it runs the file through a translator called [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
that looks for specially-formatted commands embedded in the file.
6. Commands can be embedded in the body of a page.
@@ -101,7 +101,7 @@ rather than Git itself.
which tells Jekyll to copy the contents of `somefile.html` into the file being translated;
this is used to create standard headers and footers for pages.
Another is `{{variable}}`:
- when Jekyll see this,
+ when Jekyll sees this,
it replaces it with the value of `variable`.
This is used to insert things like a contact email address and the URL for our Twitter account.
@@ -370,7 +370,7 @@ Lesson Material
in directories under `intermediate`.
3. Our old lesson material
is in the `lessons` directory.
- We plan to retire it in Spring 2014,
+ We plan to retire it in Spring 2014.
As explained [below](#building-things),
you can use `make` to compile this material in the way that GitHub does
@@ -422,7 +422,7 @@ The most important files and directories are **highlighted**.
* _layouts/ - Jekyll page layouts.
* **_site/** - output directory (created when building the site locally).
* _templates/ - template files for conversion of IPython Notebooks to Markdown.
- Templates for other conversion systems (e.g., Pandoc) should go here too.
+ Templates for other conversion systems (e.g., Pandoc) should go here, too.
* bib.md - bibliography.
* bin/ - miscellaneous tools used in building the site.
* book.md - generated when compiling the website locally.
@@ -503,7 +503,7 @@ FAQ
Uninstall pygments.rb 0.5.1 or 0.5.2, install 0.5.0. For example, here's how you would
uninstall pygments 0.5.2 and restore version 0.5.0:
- ~~~
+ ~~~
$ gem uninstall pygments.rb --version "=0.5.2"
$ gem install pygments.rb --version "=0.5.0"
~~~
@@ -512,7 +512,7 @@ FAQ
The output of `make check` looks like this:
- ~~~
+ ~~~
WARNING: Unrecognized alias: 'output', it will probably have no effect.[TerminalIPythonApp] File not found: u'nbconvert'
cp tmp/python/novice/01-numpy.html _site/python/novice/01-numpy.html
cp: cannot stat ‘tmp/python/novice/01-numpy.html’: No such file or directory
@@ -543,3 +543,4 @@ FAQ
Use subdirectories like `2013-07-01-esu/beginners`,
so that main directory names always follow our four-part convention.
+