diff --git a/docs/sources/reference/commandline/cli.md b/docs/sources/reference/commandline/cli.md
index e142afde79..0565d09385 100644
--- a/docs/sources/reference/commandline/cli.md
+++ b/docs/sources/reference/commandline/cli.md
@@ -746,7 +746,7 @@ Creates a new container.
       --ipc=""                   Default is to create a private IPC namespace (POSIX SysV IPC) for the container
                                    'container:<name|id>': reuses another container shared memory, semaphores and message queues
                                    'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
-      --link=[]                  Add link to another container in the form of name:alias
+      --link=[]                  Add link to another container in the form of <name or id>:alias
       --lxc-conf=[]              (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
       -m, --memory=""            Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
       --mac-address=""           Container MAC address (e.g. 92:d0:c6:0a:29:33)
diff --git a/docs/sources/reference/run.md b/docs/sources/reference/run.md
index 8bf0d3633f..ca7480beb8 100644
--- a/docs/sources/reference/run.md
+++ b/docs/sources/reference/run.md
@@ -512,7 +512,7 @@ or override the Dockerfile's exposed defaults:
                    Both hostPort and containerPort can be specified as a range of ports. 
                    When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
                    (use 'docker port' to see the actual mapping)
-    --link=""  : Add link to another container (name:alias)
+    --link=""  : Add link to another container (<name or id>:alias)
 
 As mentioned previously, `EXPOSE` (and `--expose`) makes ports available
 **in** a container for incoming connections. The port number on the
@@ -595,7 +595,7 @@ above, or already defined by the developer with a Dockerfile `ENV`:
 
 Similarly the operator can set the **hostname** with `-h`.
 
-`--link name:alias` also sets environment variables, using the *alias* string to
+`--link <name or id>:alias` also sets environment variables, using the *alias* string to
 define environment variables within the container that give the IP and PORT
 information for connecting to the service container. Let's imagine we have a
 container running Redis: