diff --git a/README.md b/README.md
index ec232fbcea..7ae5ec2756 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,7 @@ This can be achieved by starting Docker with the `-H` flag (e.g. `-H 0.0.0.0:237
 Currently, nodes must be running the Docker **master** version.
 Master binaries are available here: https://master.dockerproject.com/
 
-### Example usage: using the hosted discovery service
+### Example usage
 
 ```bash
 # create a cluster
@@ -51,51 +51,8 @@ $ swarm list --discovery token://6856663cdefdec325839a4b7e1de38e8
 http://<node_ip:2375>
 ```
 
-### Example usage: using a static file describing the cluster
-
-```bash
-# for each of your nodes, add a line to a file
-#  <node_ip> doesn't have to be public (eg. 192.168.0.X),
-#  as long as the other nodes can reach it, it is fine.
-$ echo <node_ip:2375> >> /tmp/my_cluster
-
-# start the manager on any machine or your laptop
-$ swarm manage --discovery file:///tmp/my_cluster --addr=<swarm_ip:swarm_port>
-
-# use the regular docker cli
-$ docker -H <swarm_ip:swarm_port> info
-$ docker -H <swarm_ip:swarm_port> run ... 
-$ docker -H <swarm_ip:swarm_port> ps 
-$ docker -H <swarm_ip:swarm_port> logs ...
-...
-
-# list nodes in your cluster
-$ swarm list --discovery file:///tmp/my_cluster
-http://<node_ip:2375>
-```
-
-### Example usage: using etcd
-
-```bash
-# on each of your nodes, start the swarm agent
-#  <node_ip> doesn't have to be public (eg. 192.168.0.X),
-#  as long as the other nodes can reach it, it is fine.
-$ swarm join --discovery etcd://<etcd_ip>/>path> --addr=<node_ip:2375>
-
-# start the manager on any machine or your laptop
-$ swarm manage --discovery etcd://<etcd_ip>/>path> --addr=<swarm_ip:swarm_port>
-
-# use the regular docker cli
-$ docker -H <swarm_ip:swarm_port> info
-$ docker -H <swarm_ip:swarm_port> run ... 
-$ docker -H <swarm_ip:swarm_port> ps 
-$ docker -H <swarm_ip:swarm_port> logs ...
-...
-
-# list nodes in your cluster
-$ swarm list --discovery etcd://<etcd_ip>/>path>
-http://<node_ip:2375>
-```
+See [here](https://github.com/docker/swarm/discovery) for more information about
+other discovery services.
 
 ### TLS
 
diff --git a/discovery/README.md b/discovery/README.md
index 34c1a78ea0..7d3a69c4a3 100644
--- a/discovery/README.md
+++ b/discovery/README.md
@@ -1,17 +1,100 @@
 Discovery
 =========
 
+`Docker Swarm` comes with multiple Discovery backends
+
+## Examples
+
+##### Using the hosted discovery service
+
+```bash
+# create a cluster
+$ swarm create
+6856663cdefdec325839a4b7e1de38e8
+
+# on each of your nodes, start the swarm agent
+#  <node_ip> doesn't have to be public (eg. 192.168.0.X),
+#  as long as the other nodes can reach it, it is fine.
+$ swarm join --discovery token://6856663cdefdec325839a4b7e1de38e8 --addr=<node_ip:2375>
+
+# start the manager on any machine or your laptop
+$ swarm manage --discovery token://6856663cdefdec325839a4b7e1de38e8 --addr=<swarm_ip:swarm_port>
+
+# use the regular docker cli
+$ docker -H <swarm_ip:swarm_port> info
+$ docker -H <swarm_ip:swarm_port> run ... 
+$ docker -H <swarm_ip:swarm_port> ps 
+$ docker -H <swarm_ip:swarm_port> logs ...
+...
+
+# list nodes in your cluster
+$ swarm list --discovery token://6856663cdefdec325839a4b7e1de38e8
+http://<node_ip:2375>
+```
+
+###### Using a static file describing the cluster
+
+```bash
+# for each of your nodes, add a line to a file
+#  <node_ip> doesn't have to be public (eg. 192.168.0.X),
+#  as long as the other nodes can reach it, it is fine.
+$ echo <node_ip:2375> >> /tmp/my_cluster
+
+# start the manager on any machine or your laptop
+$ swarm manage --discovery file:///tmp/my_cluster --addr=<swarm_ip:swarm_port>
+
+# use the regular docker cli
+$ docker -H <swarm_ip:swarm_port> info
+$ docker -H <swarm_ip:swarm_port> run ... 
+$ docker -H <swarm_ip:swarm_port> ps 
+$ docker -H <swarm_ip:swarm_port> logs ...
+...
+
+# list nodes in your cluster
+$ swarm list --discovery file:///tmp/my_cluster
+http://<node_ip:2375>
+```
+
+###### Using etcd
+
+```bash
+# on each of your nodes, start the swarm agent
+#  <node_ip> doesn't have to be public (eg. 192.168.0.X),
+#  as long as the other nodes can reach it, it is fine.
+$ swarm join --discovery etcd://<etcd_ip>/>path> --addr=<node_ip:2375>
+
+# start the manager on any machine or your laptop
+$ swarm manage --discovery etcd://<etcd_ip>/>path> --addr=<swarm_ip:swarm_port>
+
+# use the regular docker cli
+$ docker -H <swarm_ip:swarm_port> info
+$ docker -H <swarm_ip:swarm_port> run ... 
+$ docker -H <swarm_ip:swarm_port> ps 
+$ docker -H <swarm_ip:swarm_port> logs ...
+...
+
+# list nodes in your cluster
+$ swarm list --discovery etcd://<etcd_ip>/>path>
+http://<node_ip:2375>
+```
+
+## Contributing
+
 Contributing a new discovery backend is easy,
 simply implements this interface:
 
 ```go
 type DiscoveryService interface {
+     Initialize(string, int) error
      Fetch() ([]string, error)
-     Watch(int) <-chan time.Time
+     Watch() <-chan time.Time
      Register(string) error
 }
 ```
 
+######Initialize
+take the `--dicovery` withtout the scheme and a heartbeat (in seconds)
+
 ######Fetch
 returns the list of all the nodes from the discovery