diff --git a/README.md b/README.md
index c25167c..3773f37 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,8 @@ StrawBoss must know about the projects it builds. For each project, StrawBoss
 must be configured with a unique project name and a URL or repo-specification
 that can be passed to `git clone` to clone the project.
 
-For more details see the Service Project Definitions section.
+For more details see the
+[Service Project Definition](#service-project-definition) section.
 
 ## Artifacts Repo
 
@@ -52,7 +53,7 @@ are:
 
 All are required.
 
-#### Service Project Definitions
+#### Service Project Definition
 
 Project definitions are JSON objects with the following keys:
 
@@ -69,9 +70,9 @@ Project definitions are JSON objects with the following keys:
   `master`)*.
 
 * `cfgFilePath` *(optional)*: path to the StrawBoss project configuration file
-  (see the Project Configuration section). If this is a relative path it is
-  resolved relative to the project root directory. *(defaults to
-  `strawboss.json`)*.
+  (see the [Project Configuration](#project-configuration) section). If this is
+  a relative path it is resolved relative to the project root directory.
+  *(defaults to `strawboss.json`)*.
 
 * `envVars` *(optional)*: an object whose key-value pairs are expected to be
   strings. Each pair will be added as an environment variable to the runtime
@@ -82,10 +83,11 @@ Project definitions are JSON objects with the following keys:
 The build configuration for each project lives in the project itself. In the
 root directory of the project repo StrawBoss expects to find a project
 configuration file named `strawboss.json` (this location can be configured, see
-the Service Project Definitions section). The project configuration file
-tells StrawBoss what steps of a project are available to be built, and how to
-initiate the build for each step. Steps can be dependant on each other, as long
-as they do not define any circular references.
+the [Service Project Definition](#service-project-definition) section). The
+project configuration file tells StrawBoss what steps of a project are
+available to be built, and how to initiate the build for each step. Steps can
+be dependant on each other, as long as they do not define any circular
+references.
 
 The contents of a project configurations files is expected to be a valid JSON
 object. The top level keys are:
@@ -95,7 +97,7 @@ object. The top level keys are:
 
 * `steps` *(required)*: an object of step definitions. Each of this object's
   keys is the name of a step. The corresponding value is the step definition.
-  (see the Step Definitions section for details).
+  (see the [Step Definition](#step-definition) section for details).
 
 * `versionCmd` *(optional)*: a command to be run in a shell (`sh`-compatible)
   that is expected to print the current version of the project on `stdout`.
@@ -110,7 +112,8 @@ When performing a build, StrawBoss:
 3.  checkout the revision or branch requested for this run
 4.  load the project's StrawBoss configuration file.
 5.  merge environment variables defined in the project configuration
-6.  run `versionCmd` to get the current project version
+6.  run `versionCmd` to get the current project version. The result is stored
+    in the `VERSION` environment variable.
 7.  check the environment variables against `expectedEnv`
 8.  check that all the steps named in `depends` have already been run and run
     them if they have not. For each step named in `depends` an environment
@@ -124,7 +127,7 @@ When performing a build, StrawBoss:
 10. the files named in `artifacts` are copied into the artifacts repo for this
     step and version.
 
-####  Step Definitions
+####  Step Definition
 
 Step definitions are JSON objects with the following keys:
 
@@ -158,11 +161,11 @@ Step definitions are JSON objects with the following keys:
   in the build environment it will cause StrawBoss to fail this step.
   *(defaults to `[]`)*.
 
-* `dontCache` *(optional)*: boolean. StrawBoss remembers the steps it has run
-  and caches the artifacts generated by them.  Future builds for the same
+* `dontSkip` *(optional)*: boolean. StrawBoss remembers the steps it has run
+  and caches the artifacts generated by them. Future builds for the same
   version that request this step normally will not cause StrawBoss to re-run
-  the step. If `dontCache` is set to `true`, the output of this step will not
-  be cached, causing this step to always be run when it is referenced.
+  the step. If `dontSkip` is set to `true`, the output of this step will always
+  be run when it is referenced, regardless of previous cached results.
 
 ## Architecture