diff --git a/docs/reference/commandline/service_create.md b/docs/reference/commandline/service_create.md
index 25d0c17c61..2eeae5d13e 100644
--- a/docs/reference/commandline/service_create.md
+++ b/docs/reference/commandline/service_create.md
@@ -736,7 +736,7 @@ etjpu59cykrptrgw0z0hk5snf
 After you create an overlay network in swarm mode, all manager nodes have
 access to the network.
 
-When you create a service and pass the --network flag to attach the service to
+When you create a service and pass the `--network` flag to attach the service to
 the overlay network:
 
 ```bash
@@ -754,6 +754,9 @@ The swarm extends my-network to each node running the service.
 Containers on the same network can access each other using
 [service discovery](https://docs.docker.com/engine/swarm/networking/#use-swarm-mode-service-discovery).
 
+Long form syntax of `--network` allows to specify list of aliases and driver options:  
+`--network name=my-network,alias=web1,driver-opt=field1=value1`
+
 ### Publish service ports externally to the swarm (-p, --publish)
 
 You can publish service ports to make them available externally to the swarm
diff --git a/docs/reference/commandline/service_update.md b/docs/reference/commandline/service_update.md
index 41ca539119..5c43f02099 100644
--- a/docs/reference/commandline/service_update.md
+++ b/docs/reference/commandline/service_update.md
@@ -181,7 +181,7 @@ myservice
 
 Use the `--publish-add` or `--publish-rm` flags to add or remove a published
 port for a service. You can use the short or long syntax discussed in the
-[docker service create](service_create/#attach-a-service-to-an-existing-network-network)
+[docker service create](service_create/#publish-service-ports-externally-to-the-swarm)
 reference.
 
 The following example adds a published service port to an existing service.
@@ -192,6 +192,22 @@ $ docker service update \
   myservice
 ```
 
+### Add or remove network
+
+Use the `--network-add` or `--network-rm` flags to add or remove a network for
+a service. You can use the short or long syntax discussed in the
+[docker service create](service_create/#attach-a-service-to-an-existing-network-network)
+reference.
+
+The following example adds a new alias name to an existing service already connected to network my-network:
+
+```bash
+$ docker service update \
+  --network-rm my-network \
+  --network-add name=my-network,alias=web1 \
+  myservice
+```
+
 ### Roll back to the previous version of a service
 
 Use the `--rollback` option to roll back to the previous version of the service.