wording

1 files changed, 15 insertions, 10 deletions

diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst
index 4468e95b4..570d20ec7 100644
--- a/docs/narr/extconfig.rst
+++ b/docs/narr/extconfig.rst
@@ -140,17 +140,22 @@ directive did this:
    config.add_jammyjam('first')
    config.add_jammyjam('second')
 
-When the action list was committed, the user's application would not start,
-because the discriminators of the actions generated by the two calls are in
-direct conflict.  Automatic conflict resolution cannot resolve the conflict,
-and the user provided no intermediate
+When the action list was committed resulting from the set of calls above, our
+user's application would not start, because the discriminators of the actions
+generated by the two calls are in direct conflict.  Automatic conflict
+resolution cannot resolve the conflict (because no ``config.include`` is
+involved), and the user provided no intermediate
 :meth:`pyramid.config.Configurator.commit` call between the calls to
 ``add_jammyjam`` to ensure that the successive calls did not conflict with
-each other.  This is the purpose of the discriminator argument to the action
+each other.
+
+This demonstrates the purpose of the discriminator argument to the action
 method: it's used to indicate a uniqueness constraint for an action.  Two
 actions with the same discriminator will conflict unless the conflict is
 automatically or manually resolved. A discriminator can be any hashable
-object, but it is generally a string or a tuple.
+object, but it is generally a string or a tuple.  *You use a discriminator to
+declaratively ensure that the user doesn't provide ambiguous configuration
+statements.*
 
 But let's imagine that a consumer of ``add_jammyjam`` used it in such a way
 that no configuration conflicts are generated.
@@ -160,7 +165,7 @@ that no configuration conflicts are generated.
 
    config.add_jammyjam('first')
 
-What happens then?  When the ``add_jammyjam`` method is called, an action is
+What happens now?  When the ``add_jammyjam`` method is called, an action is
 appended to the pending actions list.  When the pending configuration actions
 are processed during :meth:`~pyramid.config.Configurator.commit`, and no
 conflicts occur, the *callable* provided as the second argument to the
@@ -170,9 +175,9 @@ called with no arguments.  The callable in ``add_jammyjam`` is the
 ``config.registry.jammyjam`` to whatever the user passed in as the
 ``jammyjam`` argument to the ``add_jammyjam`` function.  Therefore, the
 result of the user's call to our directive will set the ``jammyjam``
-attribute of the registry to the string ``first``.  A callable is used by a
-directive to defer the result of a user's call to a directive until conflict
-detection has had a chance to do its job.
+attribute of the registry to the string ``first``.  *A callable is used by a
+directive to defer the result of a user's call to the directive until
+conflict detection has had a chance to do its job*.
 
 Other arguments exist to the :meth:`~pyramid.config.Configurator.action`
 method, including ``args``, ``kw``, ``order``, and ``introspectables``.