From eb4a98c0d141063c2d112c4de879e226a3c96c5e 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

copyedit to make  show as file format

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 6441297f..55d4109d 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"