diff --git a/docs/reference/commandline/network_connect.md b/docs/reference/commandline/network_connect.md
index 866526effa..223fd48234 100644
--- a/docs/reference/commandline/network_connect.md
+++ b/docs/reference/commandline/network_connect.md
@@ -15,6 +15,9 @@ parent = "smn_cli"
     Connects a container to a network
 
       --help             Print usage
+      --ip               IP Address
+      --ip6              IPv6 Address
+      --link=[]          Add a link to another container
 
 Connects a container to a network. You can connect a container by name
 or by ID. Once connected, the container can communicate with other containers in
@@ -33,7 +36,13 @@ $ docker run -itd --net=multi-host-network busybox
 You can specify the IP address you want to be assigned to the container's interface.
 
 ```bash
-$ docker network connect multi-host-network --ip 10.10.36.122 container2
+$ docker network connect --ip 10.10.36.122 multi-host-network container2
+```
+
+You can use `--link` option to link another container with a prefered alias
+
+```bash
+$ docker network connect --link container1:c1 multi-host-network container2
 ```
 
 You can pause, restart, and stop containers that are connected to a network.
@@ -60,3 +69,4 @@ You can connect a container to one or more networks. The networks need not be th
 * [network ls](network_ls.md)
 * [network rm](network_rm.md)
 * [Understand Docker container networks](../../userguide/networking/dockernetworks.md)
+* [Work with networks](../../userguide/networking/work-with-networks.md)
diff --git a/docs/reference/run.md b/docs/reference/run.md
index e802f3e177..8741e3c3c4 100644
--- a/docs/reference/run.md
+++ b/docs/reference/run.md
@@ -1301,12 +1301,12 @@ specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be
 bound to 42800 on the host. To find the mapping between the host ports
 and the exposed ports, use `docker port`.
 
-If the operator uses `--link` when starting a new client container, then the
-client container can access the exposed port via a private networking interface.
-Linking is a legacy feature that is only supported on the default bridge
-network. You should prefer the Docker networks feature instead. For more
-information on this feature, see the [*Docker network
-overview*""](../userguide/networking/index.md)).
+If the operator uses `--link` when starting a new client container in the
+default bridge network, then the client container can access the exposed
+port via a private networking interface.
+If `--link` is used when starting a container in a user-defined network as
+described in [*Docker network overview*""](../userguide/networking/index.md)),
+it will provide a named alias for the container being linked to.
 
 ### ENV (environment variables)