Improve wording of kube-addon page

site/kube-addon.md

@@ -3,59 +3,68 @@ title: Integrating Kubernetes via the Addon
 menu_order: 63
 ---
 
-## Installation
+The following topics are discussed:
 
-If you're using Kubernetes 1.4 or later, and it is configured to use
-CNI, it is possible to install Weave Net on your cluster with a single
+* [Installation](#install)
+* [Network Policy Controller](#npc)
+ * [Upgrading the Daemon Sets](#daemon-sets)
+* [Network Policy Controller](#npc)
+ * [Troubleshooting Blocked Connections](#blocked-connections)
+ * [Changing Configuration Options](#configuration-options)
+
+
+##<a name=”install”></a> Installation
+
+In versions of Kubernetes that are 1.4 or greater and that is also configured to use
+[CNI](/site/cni-plugin.md), Weave Net can be installed onto your cluster with a single
 command:
 
 ```
 kubectl apply -f https://git.io/weave-kube
 ```
 
-After a few seconds, you should have a Weave Net pod running on each
-node, and any further pods you create will be attached to the Weave
+After a few seconds, a Weave Net pod should be running on each
+Node and any further pods you create will be automatically attached to the Weave
 network.
 
 > If you do not already have a CNI-enabled cluster, you can bootstrap
 > one easily with
-> [kubeadm](http://kubernetes.io/docs/getting-started-guides/kubeadm/);
-> alternatively if you are using the older cluster set-up scripts from
-> the Kubernetes repo, you can use
+> [kubeadm](http://kubernetes.io/docs/getting-started-guides/kubeadm/).
+> Alternatively if you are using the older cluster set-up scripts from
+> the Kubernetes repo, then use:
 >
 >
 >     NETWORK_PROVIDER=cni cluster/kube-up.sh
 
-NB If you were previously using the [Weave CNI
-driver](/site/cni-plugin.md) from a full install of Weave Net with your
-cluster, you will need to uninstall it first. Shut down Kubernetes,
-then perform the following _on all nodes_:
+**Note:** If using the [Weave CNI
+Plugin](/site/cni-plugin.md) from a prior full install of Weave Net with your
+cluster, you must first uninstall it before applying the Weave-kube addon.
+Shut down Kubernetes, and _on all nodes_ perform the following:
 
  * `weave reset`
- * Remove any separate provision you have made to run weave at
+ * Remove any separate provisions you may have made to run Weave at
    boot-time, e.g. `systemd` units
  * `rm /opt/cni/bin/weave-*`
 
-You can then relaunch Kubernetes and install the addon as described
+Then relaunch Kubernetes and install the addon as described
 above.
 
 The URL [https://git.io/weave-kube](https://git.io/weave-kube) points
-to the addon YAML for the latest release of the Weave Net addon;
-historic versions will be archived on our [GitHub release
+to the YAML file for the latest release of the Weave Net addon.
+Historic versions are archived on our [GitHub release
 page](https://github.com/weaveworks/weave/releases).
 
-## Upgrading
+###<a name=”daemon-sets”></a> Upgrading the Daemon Sets
 
 Kubernetes does not currently support rolling upgrades of daemon sets,
-so you will need to perform the procedure manually:
+and so you will need to perform the procedure manually:
 
 * Apply the updated addon manifest `kubectl apply -f https://git.io/weave-kube`
-* Kill each weave net pod in turn with kubectl delete; wait for the
-  replacement to begin running before moving on to the next.
+* Kill each Weave Net pod with `kubectl delete` and then wait for it to reboot before moving on to the next pod.
 
 ##<a name="npc"></a>Network Policy Controller
 
-The addon supports the [Kubernetes policy
+The addon also supports the [Kubernetes policy
 API](http://kubernetes.io/docs/user-guide/networkpolicies/) so that
 you can securely isolate pods from each other based on namespaces and
 labels. For more information on configuring network policies in
@@ -64,15 +73,15 @@ Kubernetes see the
 and the [NetworkPolicy API object
 definition](http://kubernetes.io/docs/api-reference/extensions/v1beta1/definitions/#_v1beta1_networkpolicy).
 
-### Blocked connections
+###<a name=”blocked-connections”></a> Troubleshooting Blocked Connections
 
-If you suspect that legitimate traffic is being blocked by the Weave Network Policy Controller, you may want to look at the `weave-npc` container's logs:
+If you suspect that legitimate traffic is being blocked by the Weave Network Policy Controller, check the `weave-npc` container's logs:
 
 ```
 $ kubectl logs $(kubectl get pods --all-namespaces | grep weave-net | awk '{print $2}') -n kube-system weave-npc
 ```
 
-Any time the Weave Network Policy Controller blocks a connection, it will log details about it:
+When the Weave Network Policy Controller blocks a connection, it logs the following details about it:
 
 * protocol used, 
 * source IP and port, 
@@ -85,9 +94,9 @@ TCP connection from 10.32.0.7:56648 to 10.32.0.11:80 blocked by Weave NPC.
 UDP connection from 10.32.0.7:56648 to 10.32.0.11:80 blocked by Weave NPC.
 ```
 
-## Changing Configuration Options
+###<a name=”configuration-options”></a> Changing Configuration Options
 
-You can change the default configuration by saving and editing the
-addon YAML before you `kubectl apply`. Additional arguments can be
+The default configuration settings can be changed by saving and editing the
+addon YAML before running `kubectl apply`. Additional arguments may be
 supplied to the Weave router process by adding them to the `command:`
-array in the yaml file.
+array in the YAML file.