Add missing doc for the spread strategy

Signed-off-by: Victor Vieux <victorvieux@gmail.com>

scheduler/strategy/README.md

@@ -6,23 +6,52 @@ page_keywords: docker, swarm, clustering, strategies
 
 # Strategies
 
-The `Docker Swarm` scheduler comes with multiple strategies.
+The Docker Swarm scheduler features multiple strategies for ranking nodes. The
+strategy you choose determines how Swarm computes ranking. When you run a new
+container, Swarm chooses to place it on the node with the highest computed ranking
+for your chosen strategy.
 
-These strategies are used to rank nodes using a scores computed by the strategy.
+To choose a ranking strategy, pass the `--strategy` flag and a strategy value to
+the `swarm manage` command. Swarm currently supports these values:
 
-`Docker Swarm` currently supports 2 strategies:
+* `spread`
-* [BinPacking](#binpacking-strategy)
+* `binpack`
-* [Random](#random-strategy)
+* `random`
 
-You can choose the strategy you want to use with the `--strategy` flag of `swarm manage`
+The `spread` and `binpack` strategies compute rank according to a node's
+available CPU, its RAM, and the number of containers it is running. The `random`
+strategy uses no computation. It selects a node at random and is primarily
+intended for debugging.
 
-## BinPacking strategy
+Your goal in choosing a strategy is to best optimize your swarm according to
+your company's needs. 
 
-The BinPacking strategy will rank the nodes using their CPU and RAM available and will return the
+Under the `spread` strategy, Swarm optimizes for the node with the least number
-node the most packed already. This avoid fragmentation, it will leave room for bigger containers
+of running containers. The `binpack` strategy causes Swarm to optimize for the
-on unused machines.
+container which is most packed. The `random` strategy, like it sounds, chooses
+nodes at random regardless of their available CPU or RAM.
 
-For instance, let's says that both `node-1` and `node-2` have 2G of RAM:
+Using the `spread` strategy results in containers spread thinly over many
+machines. The advantage of this strategy is that if a node goes down you only
+loose a few containers. 
+
+The `binpack` strategy avoids fragmentation because it leaves room for bigger
+containers on unused machines. The strategic advantage of `binpack` is that you
+use fewer machines as Swarm tries to pack as many containers as it can on a
+node. 
+
+If you do not specify a `--strategy` Swarm uses `spread` by default.
+
+
+## Spread strategy example
+
+In this example, your swarm is using the `spread` strategy which optimizes for
+nodes that have the fewest containers. In this swarm, both `node-1` and `node-2`
+have 2G of RAM, 2 CPUs, and neither node is running a container. Under this strategy
+`node-1` and `node-2` have the same ranking. 
+
+When you run a new container, the system chooses `node-1` at random from the swarm
+of two equally ranked nodes:
 
 ```bash
 $ docker run -d -P -m 1G --name db mysql
@@ -33,10 +62,40 @@ CONTAINER ID        IMAGE               COMMAND             CREATED
 f8b693db9cd6        mysql:latest        "mysqld"            Less than a second ago   running             192.168.0.42:49178->3306/tcp    node-1      db
 ```
 
-In this case, `node-1` was chosen randomly, because no container were running, so `node-1` and
+Now, we start another container and ask for 1G of RAM again.
-`node-2` had the same score.
 
-Now we start another container, asking for 1G of RAM again.
+```bash
+$ docker run -d -P -m 1G --name frontend nginx
+963841b138d8
+
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
+963841b138d8        nginx:latest        "nginx"             Less than a second ago   running             192.168.0.42:49177->80/tcp      node-2      frontend
+f8b693db9cd6        mysql:latest        "mysqld"            Up About a minute        running             192.168.0.42:49178->3306/tcp    node-1      db
+```
+
+The container `frontend` was started on `node-2` because it was the node the
+least packed already. If two nodes have the same amount of available RAM and
+CPUs, the `spread` strategy prefers the node with least containers running.
+
+
+## BinPack strategy example
+
+In this example, let's says that both `node-1` and `node-2` have 2G of RAM and
+neither is running a container. Again, the nodes are equal. When you run a new
+container, the system chooses `node-1` at random from the swarm:
+
+
+```bash
+$ docker run -d -P -m 1G --name db mysql
+f8b693db9cd6
+
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND             CREATED                  STATUS              PORTS                           NODE        NAMES
+f8b693db9cd6        mysql:latest        "mysqld"            Less than a second ago   running             192.168.0.42:49178->3306/tcp    node-1      db
+```
+
+Now, you start another container, asking for 1G of RAM again.
 
 ```bash
 $ docker run -d -P -m 1G --name frontend nginx
@@ -48,16 +107,17 @@ CONTAINER ID        IMAGE               COMMAND             CREATED
 f8b693db9cd6        mysql:latest        "mysqld"            Up About a minute        running             192.168.0.42:49178->3306/tcp    node-1      db
 ```
 
-The container `frontend` was also started on `node-1` because it was the node the most packed
+The system starts the new `frontend` container on `node-1` because it was the
-already. This allows us to start a container requiring 2G of RAM on `node-2`.
+node the most packed already. This allows us to start a container requiring 2G
+of RAM on `node-2`.
 
-## Random strategy
+If two nodes have the same amount of available RAM and CPUs, the `binpack`
+strategy prefers the node with most containers running.
 
-The Random strategy, as it's name says, chooses a random node, it's used mainly for debug.
 
 ## Docker Swarm documentation index
 
 - [User guide](https://docs.docker.com/swarm/)
 - [Discovery options](https://docs.docker.com/swarm/discovery/)
 - [Scheduler filters](https://docs.docker.com/swarm/scheduler/filter/)
-- [Swarm API](https://docs.docker.com/swarm/API/)
+- [Swarm API](https://docs.docker.com/swarm/API/)