wording

1 files changed, 41 insertions, 41 deletions

diff --git a/docs/narr/configuration.rst b/docs/narr/configuration.rst
index 85e755c4a..394603946 100644
--- a/docs/narr/configuration.rst
+++ b/docs/narr/configuration.rst
@@ -8,11 +8,11 @@ Application Configuration
 
 Each deployment of an application written using :app:`Pyramid` implies a
 specific *configuration* of the framework itself.  For example, an
-application which serves up MP3s for user consumption might plug code into
-the framework that manages songs, while an application that manages corporate
-data might plug in code that manages accounting information.  The way in which
-code is plugged in to :app:`Pyramid`, for a specific application, is referred
-to as "configuration".
+application which serves up MP3 files for your listening enjoyment might plug
+code into the framework that manages song files, while an application that
+manages corporate data might plug in code that manages accounting
+information.  The way in which code is plugged in to :app:`Pyramid` for a
+specific application is referred to as "configuration".
 
 Most people understand "configuration" as coarse settings that inform the
 high-level operation of a specific application deployment.  For instance,
@@ -67,14 +67,16 @@ including conditionals, can be employed in this mode of configuration.
 Configuration Decorations and Code Scanning
 -------------------------------------------
 
-An alternate mode of configuration lends more *locality of reference* to a
+A different mode of configuration gives more *locality of reference* to a
 :term:`configuration declaration`.  It's sometimes painful to have all
-configuration done in imperative code, because you may need to have two files
-open at once to see the "big picture": the file that represents the
-configuration, and the file that contains the implementation objects
-referenced by the configuration.  To avoid this, :app:`Pyramid` allows you to
-insert :term:`configuration decoration` statements very close to code that is
-referred to by the declaration itself.  For example:
+configuration done in imperative code, because often the code for a single
+application may live in many files.  If the configuration is centralized in
+one place, you'll need to have at least two files open at once to see the
+"big picture": the file that represents the configuration, and the file that
+contains the implementation objects referenced by the configuration.  To
+avoid this, :app:`Pyramid` allows you to insert :term:`configuration
+decoration` statements very close to code that is referred to by the
+declaration itself.  For example:
 
 .. code-block:: python
    :linenos:
@@ -87,20 +89,19 @@ referred to by the declaration itself.  For example:
        return Response('Hello')
 
 The mere existence of configuration decoration doesn't cause any
-configuration registration to be made.  Before it hasany effect on the
+configuration registration to be performed.  Before it has any effect on the
 configuration of a :app:`Pyramid` application, a configuration decoration
 within application code must be found through a process known as a
 :term:`scan`.
 
-The :class:`pyramid.view.view_config` decorator above adds an
-attribute to the ``hello`` function, making it available for a
-:term:`scan` to find it later.
+For example, the :class:`pyramid.view.view_config` decorator in the code
+example above adds an attribute to the ``hello`` function, making it
+available for a :term:`scan` to find it later.
 
-:app:`Pyramid` is willing to :term:`scan` a module or a package and
-its subpackages for decorations when the
-:meth:`pyramid.config.Configurator.scan` method is invoked:
-scanning implies searching for configuration declarations in a package
-and its subpackages.  For example:
+A :term:`scan` of a :term:`module` or a :term:`package` and its subpackages
+for decorations happens when the :meth:`pyramid.config.Configurator.scan`
+method is invoked: scanning implies searching for configuration declarations
+in a package and its subpackages.  For example:
 
 .. topic:: Starting A Scan
 
@@ -122,22 +123,21 @@ and its subpackages.  For example:
           app = config.make_wsgi_app()
           serve(app, host='0.0.0.0')
 
-The scanning machinery imports each module and subpackage in a package
-or module recursively, looking for special attributes attached to
-objects defined within a module.  These special attributes are
-typically attached to code via the use of a :term:`decorator`.  For
-example, the :class:`pyramid.view.view_config` decorator can be
-attached to a function or instance method.
+The scanning machinery imports each module and subpackage in a package or
+module recursively, looking for special attributes attached to objects
+defined within a module.  These special attributes are typically attached to
+code via the use of a :term:`decorator`.  For example, the
+:class:`pyramid.view.view_config` decorator can be attached to a function or
+instance method.
 
-Once scanning is invoked, and :term:`configuration decoration` is
-found by the scanner, a set of calls are made to a
-:term:`Configurator` on behalf of the developer: these calls represent
-the intent of the configuration decoration.
+Once scanning is invoked, and :term:`configuration decoration` is found by
+the scanner, a set of calls are made to a :term:`Configurator` on your
+behalf: these calls replace the need to add imperative configuration
+statements that don't live near the code being configured.
 
-In the example above, this is best represented as the scanner
-translating the arguments to :class:`pyramid.view.view_config` into a
-call to the :meth:`pyramid.config.Configurator.add_view`
-method, effectively:
+In the example above, the scanner translates the arguments to
+:class:`pyramid.view.view_config` into a call to the
+:meth:`pyramid.config.Configurator.add_view` method, effectively:
 
 .. ignore-next-block
 .. code-block:: python
@@ -150,10 +150,10 @@ Declarative Configuration
 
 A third mode of configuration can be employed when you create a
 :app:`Pyramid` application named *declarative configuration*.  This mode uses
-:term:`ZCML` to represent configuration statements rather than Python.  ZCML
-is often used when application extensibility is important.  Most of the
-examples in the narrative portion of this documentation concentrate on
-imperative configuration rather than ZCML, but almost everything that can be
-configured imperatively can also be configured via ZCML.  See
-:ref:`declarative_chapter` for more information about ZCML.
+an XML language known as :term:`ZCML` to represent configuration statements
+rather than Python.  ZCML is often used when application extensibility is
+important.  Most of the examples in the narrative portion of this
+documentation concentrate on imperative configuration rather than ZCML, but
+almost everything that can be configured imperatively can also be configured
+via ZCML.  See :ref:`declarative_chapter` for more information about ZCML.