4 files changed, 103 insertions, 33 deletions
diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst
index 68be4ee7c..eb2445864 100644
--- a/docs/tutorials/wiki2/basiclayout.rst
+++ b/docs/tutorials/wiki2/basiclayout.rst
@@ -43,9 +43,9 @@ above is executed.  It accepts some settings and returns a :term:`WSGI`
 application.  (See :ref:`startup_chapter` for more about ``pserve``.)
 
 The main function first creates a :term:`SQLAlchemy` database engine using
-``engine_from_config`` from the ``sqlalchemy.`` prefixed settings in the
-``development.ini`` file's ``[app:main]`` section.  This will be a URI
-(something like ``sqlite://``):
+:func:`sqlalchemy.engine_from_config` from the ``sqlalchemy.`` prefixed
+settings in the ``development.ini`` file's ``[app:main]`` section.
+This will be a URI (something like ``sqlite://``):
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
       :lines: 13
@@ -226,7 +226,7 @@ To give a simple example of a  model class, we define one named ``MyModel``:
       :linenos:
       :language: py
 
-Our example model has an ``__init__`` method that takes a two arguments
+Our example model has an ``__init__`` method that takes two arguments
 (``name``, and ``value``).  It stores these values as ``self.name`` and
 ``self.value``
 within the ``__init__`` function itself.  The ``MyModel`` class also has a
diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst
index 99f7969bc..60427a911 100644
--- a/docs/tutorials/wiki2/definingmodels.rst
+++ b/docs/tutorials/wiki2/definingmodels.rst
@@ -34,7 +34,7 @@ sample and we're not going to use it.
 
 Then, we added a ``Page`` class.  Because this is a SQLAlchemy application,
 this class inherits from an instance of
-:class:`sqlalchemy.ext.declarative.declarative_base`.
+:func:`sqlalchemy.ext.declarative.declarative_base`.
 
 .. literalinclude:: src/models/tutorial/models.py
    :pyobject: Page
@@ -45,9 +45,10 @@ As you can see, our ``Page`` class has a class level attribute
 ``__tablename__`` which equals the string ``'pages'``.  This means that
 SQLAlchemy will store our wiki data in a SQL table named ``pages``.  Our
 ``Page`` class will also have class-level attributes named ``id``, ``name`` and
-``data`` (all instances of :class:`sqlalchemy.Column`).  These will map to
-columns in the ``pages`` table.  The ``id`` attribute will be the primary key
-in the table.  The ``name`` attribute will be a text attribute, each value of
+``data`` (all instances of :class:`sqlalchemy.schema.Column`).
+These will map to columns in the ``pages`` table.
+The ``id`` attribute will be the primary key in the table.
+The ``name`` attribute will be a text attribute, each value of
 which needs to be unique within the column.  The ``data`` attribute is a text
 attribute that will hold the body of each page.
 
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index 5727816c8..f2ac2f85f 100644
--- a/docs/tutorials/wiki2/definingviews.rst
+++ b/docs/tutorials/wiki2/definingviews.rst
@@ -126,7 +126,7 @@ The ``view_page`` view function
 -------------------------------
 
 ``view_page()`` is used to display a single page of our
-wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
+wiki.  It renders the :term:`reStructuredText` body of a page (stored as
 the ``data`` attribute of a ``Page`` model object) as HTML.  Then it substitutes an
 HTML anchor for each *WikiWord* reference in the rendered HTML using a
 compiled regular expression.
diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst
index 255a60ec2..e646f63d2 100644
--- a/docs/tutorials/wiki2/installation.rst
+++ b/docs/tutorials/wiki2/installation.rst
@@ -2,34 +2,93 @@
 Installation
 ============
 
-Preparation
-===========
+Before You Begin
+================
+
+This tutorial assumes that you have already followed the steps in
+:ref:`installing_chapter`, thereby satisfying the following
+requirements.
+
+* Python interpreter is installed on your operating system
+* :term:`setuptools` or :term:`distribute` is installed
+* :term:`virtualenv` is installed
+
+Create and Use a Virtual Python Environment
+-------------------------------------------
+
+Next let's create a `virtualenv` workspace for our project.  We will
+use the `VENV` environment variable instead of absolute path of the
+virtual environment.
 
-Follow the steps in :ref:`installing_chapter`, but name the virtualenv
-directory ``pyramidtut``.
+**On UNIX:**
 
-Preparation, UNIX
------------------
+.. code-block:: text
+
+   $ export VENV=~/pyramidtut
+   $ virtualenv --no-site-packages $VENV
+   New python executable in /home/foo/env/bin/python
+   Installing setuptools.............done.
+
+**On Windows:**
 
-#. Install SQLite3 and its development packages if you don't already
-   have them installed.  Usually this is via your system's package
-   manager.  On a Debian system, this would be:
+Set the `VENV` environment variable.
+
+.. code-block:: text
+
+   c:\> set VENV=c:\pyramidtut
+
+Versions of Python use different paths, so you will need to adjust the
+path to the command for your Python version.
+
+Python 2.7:
+
+.. code-block:: text
+
+   c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV%
+
+Python 3.2:
+
+.. code-block:: text
+
+   c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV%
+
+Install Pyramid Into the Virtual Python Environment
+---------------------------------------------------
+
+**On UNIX:**
+
+.. code-block:: text
+
+   $ $VENV/bin/easy_install pyramid
+
+**On Windows**
+
+.. code-block:: text
+
+   c:\env> %VENV%\Scripts\easy_install pyramid
+
+SQLite3
+-------
+
+Install SQLite3 and its development packages if you don't already
+have them installed.  Usually this is via your system's package
+manager. On a Debian system, this would be:
 
    .. code-block:: text
 
       $ sudo apt-get install libsqlite3-dev
 
-#. Switch to the ``pyramidtut`` directory:
+Entering the virtualenv
+-----------------------
+
+Do not forget to switch to the ``pyramidtut`` directory.
+In order to do so, run this command if you are on Unix:
 
    .. code-block:: text
 
       $ cd pyramidtut
 
-
-Preparation, Windows
---------------------
-
-#. Switch to the ``pyramidtut`` directory:
+And run this if you are on Windows:
 
    .. code-block:: text
 
@@ -40,10 +99,20 @@ Preparation, Windows
 Making a Project
 ================
 
-Your next step is to create a project.  For this tutorial, we will use the
-:term:`scaffold` named ``alchemy``, which generates an application
-that uses :term:`SQLAlchemy` and :term:`URL dispatch`.  :app:`Pyramid`
-supplies a variety of scaffolds to generate sample projects.
+Your next step is to create a project.  For this tutorial we will use
+the :term:`scaffold` named ``alchemy`` which generates an application
+that uses :term:`SQLAlchemy` and :term:`URL dispatch`.
+
+:app:`Pyramid` supplies a variety of scaffolds to generate sample
+projects. We will use `pcreate`—a script that comes with Pyramid to
+quickly and easily generate scaffolds usually with a single command—to
+create the scaffold for our project.
+
+By passing in `alchemy` into the `pcreate` command, the script creates
+the files needed to use SQLAlchemy. By passing in our application name
+`tutorial`, the script inserts that application name into all the
+required files. For example, `pcreate` creates the
+``initialize_tutorial_db`` in the ``pyramidtut/bin`` directory.
 
 The below instructions assume your current working directory is the
 "virtualenv" named "pyramidtut".
@@ -66,11 +135,10 @@ On Windows:
    startup problems, try putting both the virtualenv and the project
    into directories that do not contain spaces in their paths.
 
-
 .. _installing_project_in_dev_mode:
 
-Installing the Project in "Development Mode"
-============================================
+Installing the Project in Development Mode
+==========================================
 
 In order to do development on the project easily, you must "register"
 the project as a development egg in your workspace using the
@@ -92,8 +160,9 @@ On Windows:
    c:\pyramidtut> cd tutorial
    c:\pyramidtut\tutorial> %VENV%\Scripts\python setup.py develop
 
-Success executing this command will end with a line to the console something
-like::
+The console will show `setup.py` checking for packages and installing
+missing packages. Success executing this command will show a line like
+the following::
 
    Finished processing dependencies for tutorial==0.0