diff --git a/components/cli/docs/reference/commandline/dockerd.md b/components/cli/docs/reference/commandline/dockerd.md
index 4ce22bde67..be214e15f5 100644
--- a/components/cli/docs/reference/commandline/dockerd.md
+++ b/components/cli/docs/reference/commandline/dockerd.md
@@ -262,7 +262,7 @@ snapshots. For each devicemapper graph location – typically
 `/var/lib/docker/devicemapper` – a thin pool is created based on two block
 devices, one for data and one for metadata. By default, these block devices
 are created automatically by using loopback mounts of automatically created
-sparse files. Refer to [Storage driver options](#storage-driver-options) below
+sparse files. Refer to [Devicemapper options](#devicemapper-options) below
 for a way how to customize this setup.
 [~jpetazzo/Resizing Docker containers with the Device Mapper plugin](http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/)
 article explains how to tune your existing setup without the use of options.
@@ -274,7 +274,7 @@ does not share executable memory between devices. Use
 The `zfs` driver is probably not as fast as `btrfs` but has a longer track record
 on stability. Thanks to `Single Copy ARC` shared blocks between clones will be
 cached only once. Use `dockerd -s zfs`. To select a different zfs filesystem
-set `zfs.fsname` option as described in [Storage driver options](#storage-driver-options).
+set `zfs.fsname` option as described in [ZFS options](#zfs-options).
 
 The `overlay` is a very fast union filesystem. It is now merged in the main
 Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). `overlay`
diff --git a/components/cli/docs/reference/commandline/service_create.md b/components/cli/docs/reference/commandline/service_create.md
index 5634d72cff..e9da856c52 100644
--- a/components/cli/docs/reference/commandline/service_create.md
+++ b/components/cli/docs/reference/commandline/service_create.md
@@ -739,7 +739,7 @@ Containers on the same network can access each other using
 You can publish service ports to make them available externally to the swarm
 using the `--publish` flag. The `--publish` flag can take two different styles
 of arguments. The short version is positional, and allows you to specify the
-target port and container port separated by a colon.
+published port and target port separated by a colon.
 
 ```bash
 $ docker service create --name my_web --replicas 3 --publish 8080:80 nginx
@@ -751,7 +751,7 @@ mode when using the short format. Here is an example of using the long format
 for the same service as above:
 
 ```bash
-$ docker service create --name my_web --replicas 3 --publish target=8080,port=80 nginx
+$ docker service create --name my_web --replicas 3 --publish published=8080,target=80 nginx
 ```
 
 The options you can specify are:
@@ -765,7 +765,7 @@ The options you can specify are:
   <th>Description</th>
 </tr>
 <tr>
-  <td>target and container port </td>
+  <td>published and target port </td>
   <td><tt></tt></td>
   <td><tt></tt></td>
   <td></td>
@@ -773,16 +773,16 @@ The options you can specify are:
 <tr>
   <td>protocol</td>
   <td><tt>--publish 8080:80</tt></td>
-  <td><tt>--publish target=8080,port=80</tt></td>
+  <td><tt>--publish published=8080,target=80</tt></td>
   <td><p>
-    The container port to publish and the target port to bind it to on the
-    routing mesh or directly on the node.
+    The port to publish the service to on the routing mesh or directly on
+    the node, and the target port on the container.
   </p></td>
 </tr>
 <tr>
   <td>mode</td>
   <td>Not possible to set using short syntax.</td>
-  <td><tt>--publish target=8080,port=80,mode=host</tt></td>
+  <td><tt>--publish published=8080,target=80,mode=host</tt></td>
   <td><p>
     The mode to use for binding the port, either `ingress` or `host`. Defaults
     to `ingress` to use the routing mesh.
@@ -791,7 +791,7 @@ The options you can specify are:
 <tr>
   <td>protocol</td>
   <td><tt>--publish 8080:80/tcp</tt></td>
-  <td><tt>--publish target=8080,port=80,protocol=tcp</tt></td>
+  <td><tt>--publish published=8080,target=80,protocol=tcp</tt></td>
   <td><p>
     The protocol to use, either `tcp` or `udp`. Defaults to `tcp`. To bind a
     port for both protocols, specify the `-p` or `--publish` flag twice.
@@ -800,7 +800,7 @@ The options you can specify are:
 </table>
 
 When you publish a service port using `ingres` mode, the swarm routing mesh
-makes the service accessible at the target port on every node regardless if
+makes the service accessible at the published port on every node regardless if
 there is a task for the service running on the node. If you use `host` mode,
 the port is only bound on nodes where the service is running, and a given port
 on a node can only be bound once. You can only set the publication mode using
diff --git a/components/cli/docs/reference/commandline/service_update.md b/components/cli/docs/reference/commandline/service_update.md
index ef9e0816d2..41ca539119 100644
--- a/components/cli/docs/reference/commandline/service_update.md
+++ b/components/cli/docs/reference/commandline/service_update.md
@@ -177,18 +177,18 @@ $ docker service update --mount-rm /somewhere myservice
 myservice
 ```
 
-### Add or remove port mappings
+### Add or remove published service ports
 
-Use the `--port-add` or `--port-rm` flags to add or remove port mappings to or
-from a service. You can use the short or long syntax discussed in the
-[docker service update](service_create/#attach-a-service-to-an-existing-network-network)
+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)
 reference.
 
-The following example adds a port mapping to an existing service.
+The following example adds a published service port to an existing service.
 
 ```bash
 $ docker service update \
-  --port-add port=80,target=8080 \
+  --publish-add published=8080,target=80 \
   myservice
 ```