1 files changed, 24 insertions, 22 deletions

diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst
index 9a5267b2a..f6e658cf0 100644
--- a/docs/narr/handlers.rst
+++ b/docs/narr/handlers.rst
@@ -19,20 +19,21 @@ predicate` to control which method of the handler is called.
    :term:`url dispatch`.  The concept of a view handler is analogous to a
    "controller" in Pylons 1.0.
 
-The view handler class is initialized by :app:`Pyramid` in the same manner as
-a view class.  Its ``__init__`` is called with a request object (see
-:ref:`class_as_view`) when a request enters the system which corresponds with
-a view handler registration made during configuration. A method of the view
-handler class is then called. The method which is called depends on the view
-handler configuration.
-
-The :meth:`pyramid.config.Configurator.add_handler` method will scan
-the handler class and automatically set up views for methods that are
-auto-exposed or were decorated with :class:`~pyramid.view.action`. The
-:class:`~pyramid.view.action` decorator is used to setup additional view
-configuration information for individual class methods, and can be used
-repeatedly for a single method to register multiple view configurations that
-will call that view callable.
+The view handler class is initialized by :app:`Pyramid` in the same
+manner as a view class.  Its ``__init__`` is called with a request
+object (see :ref:`class_as_view`) as its argument when a request enters
+the system which corresponds with a view handler registration made
+during configuration.  After the view handler class is instantiated, a
+method on the instance is called. The method which is called depends on
+the view handler configuration.
+
+The :meth:`pyramid.config.Configurator.add_handler` method will
+scan the handler class and automatically set up views for methods that
+are auto-exposed, or were decorated with the
+:class:`~pyramid.view.action` decorator. This decorator is used to setup
+additional view configuration information for individual methods of the
+class, and can be used repeatedly for a single view method to
+register multiple view configurations for it.
 
 Here's an example view handler class:
 
@@ -82,9 +83,9 @@ specific ``action`` name:
                        handler=Hello, action='index')
 
 This will result one of the methods that are configured for the ``action`` of
-'index' in the ``Hello`` handler class to be called. Other methods in the
-handler class not named 'index' might be called if they were configured to be
-called when the ``action`` name is 'index' as will be seen below.
+'index' in the ``Hello`` handler class to be called. In this case the name
+of the method is the same as the action name: 'index'. However, this
+need not be the case, as we will see below.
 
 .. note::
 
@@ -175,7 +176,7 @@ Action Decorator
 ----------------
 
 The :class:`~pyramid.view.action` decorator registers view configuration
-information on the handler method which is used by
+information on the handler method, which is used by
 :meth:`~pyramid.config.Configurator.add_handler` to setup the view
 configuration.
 
@@ -210,10 +211,11 @@ Example:
 This will register two views that require the ``action`` to be ``index``, with
 the additional view predicate requiring a specific request method.
 
-When a method is decorated multiple times with :class:`~pyramid.view.action`,
-a view configuration will be registered for each call, with the view callable
-being the method decorated. Used with a combination of ``name``, multiple
-URL's can result in different template renderings with the same data.
+It can be useful to decorate a single method multiple times with
+:class:`~pyramid.view.action`. Each action decorator will register a new view
+for the method. By specifying different names and renderers for each action,
+the same view logic can be exposed and rendered differently on multiple
+URLs.
 
 Example: