Address documentation comments

site/how-it-works.md

@@ -7,7 +7,8 @@ layout: default
 
 A weave network consists of a number of 'peers' - weave routers
 residing on different hosts. Each peer has a name, which tends to
-remain the same over restarts, and a unique identifier (UID) which is
+remain the same over restarts, a human friendly nickname for use in
+status and logging output and a unique identifier (UID) which is
 different each time it is run.  These are opaque identifiers as far as
 the router is concerned, although the name defaults to a MAC address.
 
@@ -147,6 +148,8 @@ The topology update payload is laid out like this:
     +-----------------------------------+
     | Peer 1: Name                      |
     +-----------------------------------+
+    | Peer 1: NickName                  |
+    +-----------------------------------+
     | Peer 1: UID                       |
     +-----------------------------------+
     | Peer 1: Version number            |
@@ -157,6 +160,8 @@ The topology update payload is laid out like this:
     +-----------------------------------+
     | Peer N: Name                      |
     +-----------------------------------+
+    | Peer N: NickName                  |
+    +-----------------------------------+
     | Peer N: UID                       |
     +-----------------------------------+
     | Peer N: Version number            |

site/troubleshooting.md

@@ -86,11 +86,10 @@ The terms used here are explained further at
 [how it works](how-it-works.html).
 
 The 'Our name' line identifies the local weave router as a peer in the
-weave network. It displays both the peer name and the peer's nickname
-in parenthesis; the peer name defaults to a MAC address, whilst the
-nickname defaults to the name of the host on which the weave container
-was launched. If desired the nickname can be overriden by supplying
-the `-nickname` argument to `weave launch`.
+weave network, displaying the peer name followed by the peer's nickname
+in parenthesis. The nickname defaults to the name of the host on which
+the weave container was launched; if desired it can be overriden by
+supplying the `-nickname` argument to `weave launch`.
 
 The 'Sniffing traffic' line shows details of the virtual ethernet
 interface that weave is using to receive packets on the local