diff --git a/site/features.md b/site/features.md
index 2c1448ea..3a987960 100644
--- a/site/features.md
+++ b/site/features.md
@@ -73,7 +73,7 @@ Containers started in this way that subsequently restart, either
 by an explicit `docker restart` command or by Docker restart 
 policy, are re-attached to the Weave network by the `Weave Docker API Proxy`.
 
-See [Using the Weave Docker API Proxy](/site/weave-docker-api/using-proxy.md).
+See [Integrating Docker via the API Proxy](/site/weave-docker-api.md).
 
 
 ###<a name="plugin"></a>Weave Network Docker Plugin
@@ -88,14 +88,14 @@ Using the Weave plugin enables you to take advantage of [Docker's network functi
 Also, Weave’s Docker Network plugin doesn't require an external cluster store and you can start and stop containers even 
 when there are network connectivity problems.
 
-See [Using the Weave Docker Network Plugin](/site/plugin.md) for more details.
+See [Integrating Docker via the Network Plugin](/site/plugin.md) for more details.
 
 
 ###<a name="cniplugin"></a>Weave Network CNI Plugin
 
-Weave can be used as a plugin to systems that support the [Container Network Interface](https://github.com/appc/cni), such as Kubernetes.
+Weave can be used as a plugin to systems that support the [Container Network Interface](https://github.com/appc/cni), such as Kubernetes and Mesosphere.
 
-See [Using the Weave CNI Plugin](/site/cni-plugin.md) for more details.
+See [Integrating Kubernetes and Mesos via the CNI Plugin](/site/cni-plugin.md) for more details.
 
 
 ###<a name="addressing"></a>IP Address Management (IPAM)
@@ -120,7 +120,7 @@ and are discoverable by using standard, simple name lookups:
 
 WeaveDNS also supports [load balancing](/site/weavedns/load-balance-fault-weavedns.md), [fault resilience](/site/weavedns/load-balance-fault-weavedns.md) and [hot swapping](/site/weavedns/managing-entries-weavedns.md). 
 
-See [Naming and discovery with WeaveDNS](/site/weavedns/how-works-weavedns.md).
+See [Discovering Containers with WeaveDNS](/site/weavedns.md).
  
 ###<a name="application-isolation"></a>Application Isolation
 
diff --git a/site/plugin/plugin-how-it-works.md b/site/plugin/plugin-how-it-works.md
index 54d9f26a..d04f9c2b 100644
--- a/site/plugin/plugin-how-it-works.md
+++ b/site/plugin/plugin-how-it-works.md
@@ -38,6 +38,5 @@ The plugin accepts the following options via `docker network create ... --opt`:
 
 **See Also**
 
- * [Using the Weave Net Docker Network Plugin](/site/plugin.md)
- * [Plugin Command-line Arguments](/site/plugin/plug-in-command-line.md)
- 
+ * [Integrating Docker via the Network Plugin](/site/plugin.md)
+
diff --git a/site/weave-docker-api.md b/site/weave-docker-api.md
index 179948b0..ccab0096 100644
--- a/site/weave-docker-api.md
+++ b/site/weave-docker-api.md
@@ -3,15 +3,38 @@ title: Integrating Docker via the API Proxy
 menu_order: 50
 ---
 
-
 The Docker API proxy automatically attaches containers to the Weave
 network when they are started using the ordinary Docker
 [command-line interface](https://docs.docker.com/reference/commandline/cli/)
 or the [remote API](https://docs.docker.com/reference/api/docker_remote_api/),
 instead of `weave run`.
 
+###<a name="attaching-containers"></a>Attaching Containers to a Weave Network
 
-###Setting Up The Weave Net Docker API Proxy
+There are three ways to attach containers to a Weave network (which method to use is 
+entirely up to you):
+
+**1.** The Weave Net Docker API Proxy. See [Setting Up the Weave Net Docker API Proxy](#weave-api-proxy).  
+
+**2.**  The Docker Network Plugin framework. The Docker Network Plugin is used when 
+Docker containers are started with the --net flag, for example: 
+
+`docker run --net <docker-run-options>`
+
+**Where,** 
+
+ * `<docker-run-options>` are the [docker run options](https://docs.docker.com/engine/reference/run/) 
+ you give to your container on start 
+
+Note that if a Docker container is started with the --net flag, then the Weave Docker API Proxy
+is automatically disabled and is not used to attach containers. 
+See [Integrating Docker via the Network Plugin](plugin.md).
+
+**3.** Containers can also be attached to the Weave network with `weave run` commands. This method also
+does not use the Weave Docker API Proxy. 
+See [Launching Containers With Weave Run (without the Proxy)](/site/weave-docker-api/launching-without-proxy.md). 
+
+###<a name="weave-api-proxy"></a>Setting Up The Weave Net Docker API Proxy
 
 The proxy sits between the Docker client (command line or API) and the
 Docker daemon, and intercepts the communication between the two. You can
diff --git a/site/weavedns.md b/site/weavedns.md
index 2e21d507..d9f42eb6 100644
--- a/site/weavedns.md
+++ b/site/weavedns.md
@@ -44,5 +44,5 @@ disable weaveDNS itself, launch weave with the `--no-dns` option.
 
 **See Also**
 
- * [How Weave Finds Containers](/site/weave-docker-api.md)
+ * [Integrating Docker via the API Proxy](/site/weave-docker-api.md)
  * [Load Balancing and Fault Resilience with WeaveDNS](/site/weavedns/load-balance-fault-weavedns.md)