update contributing docs to reflect current practice and clarify steps

2 files changed, 19 insertions, 15 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 16023c821..9f1ca0eae 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -274,3 +274,5 @@ Contributors
 - Zack Brunson, 2016/06/02
 
 - Marco Martinez, 2016/06/02
+
+- Cris Ewing, 2016/06/03
\ No newline at end of file
diff --git a/contributing.md b/contributing.md
index ae201d370..922d2e740 100644
--- a/contributing.md
+++ b/contributing.md
@@ -56,11 +56,15 @@ System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.ht
 
          git clone git@github.com:<username>/pyramid.git
 
+2.  Change directories into the cloned repository
+
+         cd pyramid
+
 3.  Add a git remote "upstream" for the cloned fork.
 
          git remote add upstream git@github.com:Pylons/pyramid.git
 
-4.  Set an environment variable as instructed in the
+4.  Create a virtualenv and set an environment variable as instructed in the
     [prerequisites](https://github.com/Pylons/pyramid/blob/master/HACKING.txt#L55-L58).
 
          # Mac and Linux
@@ -69,28 +73,26 @@ System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.ht
          # Windows
          set VENV=c:\hack-on-pyramid\env
 
-5.  Try to build the docs in your workspace.
+4.  Install `tox` into your virtualenv.
 
-         # Mac and Linux
-         $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build
+         $ $VENV/bin/pip install tox
 
-         # Windows
-         c:\> make clean html SPHINXBUILD=%VENV%\bin\sphinx-build
+5.  Try to build the docs in your workspace.
+
+         $ $VENV/bin/tox -e docs
 
-     If successful, then you can make changes to the documentation. You can
-     load the built documentation in the `/_build/html/` directory in a web
-     browser.
+     When the build finishes, you'll find HTML documentation rendered in
+     `.tox/docs/html`. An `epub` version will be in `.tox/docs/epub`. And the
+     result of the tests that are run on the documentation will be in
+     `.tox/docs/doctest`.
 
 6.  From this point forward, follow the typical [git
     workflow](https://help.github.com/articles/what-is-a-good-git-workflow/).
-    Start by pulling from the upstream to get the most current changes.
+    *Always* start by pulling from the upstream to get the most current changes.
 
          git pull upstream master
 
-7.  Make a branch, make changes to the docs, and rebuild them as indicated in
-    step 5.  To speed up the build process, you can omit `clean` from the above
-    command to rebuild only those pages that depend on the files you have
-    changed.
+7.  Make a branch, make changes to the docs, and rebuild them as indicated above.
 
 8.  Once you are satisfied with your changes and the documentation builds
     successfully without errors or warnings, then git commit and push them to
@@ -101,4 +103,4 @@ System](http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/install.ht
 
 9.  Create a [pull request](https://help.github.com/articles/using-pull-requests/).
 
-10.  Repeat the process starting from Step 6.
+10.  Repeat the process starting from Step 8.