From f7c923062d24e4eae5559b173af8c244d0ee9657 Mon Sep 17 00:00:00 2001
From: Victoria Bialas <victoria.bialas@docker.com>
Date: Thu, 18 Feb 2016 17:49:28 -0800
Subject: [PATCH] corrected description of network aliases, added real-world
 example per #2907

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>
---
 docs/compose-file.md | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/docs/compose-file.md b/docs/compose-file.md
index f218dc4f9..f0b7b673b 100644
--- a/docs/compose-file.md
+++ b/docs/compose-file.md
@@ -477,15 +477,13 @@ Networks to join, referencing entries under the
 
 #### aliases
 
-Aliases (alternative hostnames) for this service on the network. Other servers
-on the network can use either the service name or this alias to connect to
-this service.  Since `alias` is network-scoped:
+Aliases (alternative hostnames) for this service on the network. Other containers on the same network can use either the service name or this alias to connect to one of the service's containers.  
 
-  * the same service can have different aliases when connected to another
-    network.
-  * it is allowable to configure the same alias name to multiple containers
-    (services) on the same network.
+Since `aliases` is network-scoped, the same service can have different aliases on different networks.
 
+> **Note**: A network-wide alias can be shared by multiple containers, and even by multiple services. If it is, then exactly which container the name will resolve to is not guaranteed.
+
+The general format is shown here.
 
     networks:
       some-network:
@@ -496,6 +494,35 @@ this service.  Since `alias` is network-scoped:
         aliases:
           - alias2
 
+In the example below, three services are provided (`web`, `worker`, and `db`), along with two networks (`new` and `legacy`). The `db` service is reachable at the hostname `db` or `database` on the `new` network, and at `db` or `mysql` on the legacy network.
+
+    version: 2
+
+    services:
+      web:
+        build: ./web
+        networks:
+          - new
+
+      worker:
+        build: ./worker
+        networks:
+        - legacy
+
+      db:
+        image: mysql
+        networks:
+          new:
+            aliases:
+              - database
+          legacy:
+            aliases:
+              - mysql
+
+    networks:
+      new:
+      legacy:
+
 ### pid
 
     pid: "host"