--- a/docs/sharing.rst	Tue Apr 14 12:55:04 2015 -0400
+++ b/docs/sharing.rst	Fri Jun 20 08:19:04 2014 -0400
@@ -289,12 +289,21 @@
 mutable history with others. It does, but you have to be careful, stay
 alert, and *communicate* with your peers.
 
-A good way to start is with code review: Alice commits a draft
-changeset that Bob can review. Bob sends his comments to Alice, and
-she amends it until Bob is satisfied. Meanwhile, Bob is also
-committing draft changesets for Alice to review, amending until she is
-satisfied. Once a particular changeset passes review, the respective
-author (Alice or Bob) pushes it to the public repository.
+Code review is a good use case for sharing mutable history across
+multiple developers: Alice commits a draft changeset, submits it for
+review, and amends her changeset until her reviewer is satisfied.
+Meanwhile, Bob is also committing draft changesets for review,
+amending until his reviewer is satisfied. Once a particular changeset
+passes review, the respective author (Alice or Bob) pushes it to the
+public (publishing) repository.
+
+Incidentally, the reviewers here can be anyone: maybe Bob and Alice
+review each other's work; maybe the same third party reviews both; or
+maybe they pick different experts to review their work on different
+parts of a large codebase. Similarly, it doesn't matter if reviews are
+conducted in person, by email, or by carrier pigeon. Code review is
+outside of the scope of Mercurial, so all we're looking at here
+is the mechanics of committing, amending, pushing, and pulling.
 
 Setting up
 ==========
@@ -314,9 +323,8 @@
   updating to branch default
   1 files updated, 0 files merged, 0 files removed, 0 files unresolved
 
-We need to configure Alice's and Bob's working repositories similar to
-``test-repo``, i.e. make them non-publishing and enable ``evolve``.
-First, edit Alice's configuration with ::
+We need to configure Alice's and Bob's working repositories to enable
+``evolve``. First, edit Alice's configuration with ::
 
   $ hg -R alice config --edit --local
 
@@ -325,17 +333,19 @@
   [extensions]
   evolve = /path/to/mutable-history/hgext/evolve.py
 
-Then add the same text to Bob's repository configuration::
+Then edit Bob's repository configuration::
 
   $ hg -R bob config --edit --local
 
+and add the same text.
+
 Example 3: Alice commits and amends a draft fix
 ===============================================
 
-We'll start by following Alice working on a bug fix. We're going to
-use bookmarks to make it easier to understand multiple branch heads in
-the ``review`` repository, so Alice starts off by creating a bookmark
-and committing her first attempt at a fix::
+We'll follow Alice working on a bug fix. We're going to use bookmarks to
+make it easier to understand multiple branch heads in the ``review``
+repository, so Alice starts off by creating a bookmark and committing
+her first attempt at a fix::
 
   $ hg bookmark bug15
   $ echo 'fix' > file2
@@ -363,10 +373,8 @@
 .. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/
 .. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks
 
-Some time passes, and Alice receives her code review. (It might be by
-email, telephone, or carrier pigeon: it doesn't matter, as it's
-outside the scope of Mercurial.) As a result, Alice revises her fix
-and submits it for a second review::
+Some time passes, and Alice receives her code review. As a result,
+Alice revises her fix and submits it for a second review::
 
   $ echo 'Fix.' > file2
   $ hg amend -m 'fix bug 15 (v2)'
@@ -379,21 +387,21 @@
 
   [figure SG06: rev 2:fn1e is Alice's obsolete v1, rev 3:cbdf is her v2; both children of rev 1:de61]
 
-After a hard morning of bug fixing, Alice stops for lunch. Let's see
+After a busy morning of bug fixing, Alice stops for lunch. Let's see
 what Bob has been up to.
 
 Example 4: Bob implements and publishes a new feature
 =====================================================
 
-In the meantime, Bob has been working on a new feature. Like Alice,
-he'll use a bookmark to track his work, and he'll push that bookmark
-to the ``review`` repository, so that reviewers know which changesets
-to review. ::
+Meanwhile, Bob has been working on a new feature. Like Alice, he'll
+use a bookmark to track his work, and he'll push that bookmark to the
+``review`` repository, so that reviewers know which changesets to
+review. ::
 
   $ cd ../bob
   $ echo 'stuff' > file1
   $ hg bookmark featureX
-  $ hg commit -u bob -m 'implement feature X (v1)'
+  $ hg commit -u bob -m 'implement feature X (v1)'          # rev 4:1636
   $ hg push -B featureX
   [...]
   added 1 changesets with 1 changes to 1 files (+1 heads)
@@ -403,7 +411,7 @@
 bit, amends, and submits the resulting changeset for review::
 
   $ echo 'do stuff' > file1
-  $ hg amend -m 'implement feature X (v2)'
+  $ hg amend -m 'implement feature X (v2)'                  # rev 5:0eb7
   $ hg push
   [...]
   added 1 changesets with 1 changes to 1 files (+1 heads)
@@ -413,7 +421,7 @@
 on proper capitalization and punctuation. ::
 
   $ echo 'Do stuff.' > file1
-  $ hg amend -m 'implement feature X (v3)'
+  $ hg amend -m 'implement feature X (v3)'                  # rev 6:540b
 
 On the bright side, the second review said, "Go ahead and publish once
 you fix that." So Bob immediately publishes his third attempt::
@@ -422,10 +430,11 @@
   [...]
   added 1 changesets with 1 changes to 1 files
 
-Bob also has to update the ``review`` repository: right now it doesn't
-have his latest amendment ("v3", revision 6:540b), and it doesn't know
-that the precursor of that changeset ("v2", revision 5:0eb7) is
-obsolete. ::
+It's not enough just to update ``public``, though! Other people also
+use the ``review`` repository, and right now it doesn't have Bob's
+latest amendment ("v3", revision 6:540b), nor does it know that the
+precursor of that changeset ("v2", revision 5:0eb7) is obsolete. Thus,
+Bob pushes to ``review`` as well::
 
   $ hg push ../review
   [...]
@@ -448,9 +457,9 @@
 =========================================
 
 Finally, Alice gets back from lunch and sees that the carrier pigeon
-with her second review has arrived (or maybe she just has it in her
-email inbox). Alice's amended changeset has passed review, so she
-pushes her fix to ``public``::
+with her second review has arrived (or maybe it's in her email inbox).
+Alice's reviewer approved her amended changeset, so she pushes it to
+``public``::
 
   $ hg push ../public
   [...]
@@ -472,10 +481,10 @@
   | @  4:cbdfbd5a5db2  (alice)
   |/
 
-Since Alice and Bob are already using advanced technology in the form
-of shared mutable history, we'll assume they are perfectly comfortable
-with rebasing changesets. So Alice rebases her changeset on top of
-Bob's and publishes the result::
+We'll assume Alice and Bob are perfectly comfortable with rebasing
+changesets. (After all, they're already using mutable history in the
+form of ``amend``.) So Alice rebases her changeset on top of Bob's and
+publishes the result::
 
   $ hg rebase -d 5
   $ hg push ../public