update formatting for variables, clarify text in certain topics

Signed-off-by: Charles Smith <charles.smith@docker.com>

docs/swarm/key-concepts.md

@@ -18,8 +18,9 @@ This topic describes key concepts to help you begin using Docker Swarm.
 
 ## Swarm
 
-**Docker Swarm** is the name for the cluster management and orchestration features
-embedded in the Docker Engine.
+**Docker Swarm** is the name for the cluster management and orchestration
+features embedded in the Docker Engine. Engines that are participating in a
+cluster are running in **Swarm mode**.
 
 A **Swarm** is a cluster of Docker Engines where you deploy a set of application
 services. When you deploy an application to a Swarm, you specify the desired

docs/swarm/swarm-tutorial/add-nodes.md

@@ -19,9 +19,15 @@ to add worker nodes.
 1. Open a terminal and ssh into the machine where you want to run a worker node.
 This tutorial uses the name `worker1`.
 
-2. Run `docker swarm join MANAGER-IP:PORT` to create a worker node joined to the
-existing Swarm. Replace MANAGER-IP address of the manager node and the port
-where the manager listens.
+2. Run the following command to create a worker node joined to
+the existing Swarm:
+
+    ```
+    docker swarm join <MANAGER-IP>:<PORT>
+    ```
+
+    Replace `<MANAGER-IP>` with the address of the manager node and `<PORT>`
+    with the port where the manager listens.
 
     In the tutorial, the following command joins `worker1` to the Swarm on `manager1`:
 
@@ -34,9 +40,11 @@ where the manager listens.
 3. Open a terminal and ssh into the machine where you want to run a second
 worker node. This tutorial uses the name `worker2`.
 
-4. Run `docker swarm join MANAGER-IP:PORT` to create a worker node joined to
-the existing Swarm. Replace MANAGER-IP address of the manager node and the port
-where the manager listens.
+4. Run `docker swarm join <MANAGER-IP>:<PORT>` to create a worker node joined to
+the existing Swarm.
+
+    Replace `<MANAGER-IP>` with the address of the manager node and `<PORT>`
+    with the port where the manager listens.
 
 5. Open a terminal and ssh into the machine where the manager node runs and run
 the `docker node ls` command to see the worker nodes:

docs/swarm/swarm-tutorial/create-swarm.md

@@ -20,7 +20,11 @@ machines.
 1. Open a terminal and ssh into the machine where you want to run your manager
 node. For example, the tutorial uses a machine named `manager1`.
 
-2. Run `docker swarm init --listen-addr MANAGER-IP:PORT` to create a new Swarm.
+2. Run the following command to create a new Swarm:
+
+    ```
+    docker swarm init --listen-addr <MANAGER-IP>:<PORT>
+    ```
 
     In the tutorial, the following command creates a Swarm on the `manager1` machine:
 

docs/swarm/swarm-tutorial/delete-service.md

@@ -27,7 +27,7 @@ run your manager node. For example, the tutorial uses a machine named
     helloworld
     ```
 
-3. Run `docker service inspect SERVICE-ID` to veriy that Swarm removed the
+3. Run `docker service inspect <SERVICE-ID>` to veriy that Swarm removed the
 service. The CLI returns a message that the service is not found:
 
     ```

docs/swarm/swarm-tutorial/deploy-service.md

@@ -23,14 +23,14 @@ example, the tutorial uses a machine named `manager1`.
 2. Run the the following command:
 
     ```bash
-    $ docker service create --scale 1 --name helloworld alpine ping docker.com
+    $ docker service create --replicas 1 --name helloworld alpine ping docker.com
 
     2zs4helqu64f3k3iuwywbk49w
     ```
 
     * The `docker service create` command creates the service.
     * The `--name` flag names the service `helloworld`.
-    * The `--scale` flag specifies the desired state of 1 running instance.
+    * The `--replicas` flag specifies the desired state of 1 running instance.
     * The arguments `alpine ping docker.com` define the service as an Alpine
     Linux container that executes the command `ping docker.com`.
 

docs/swarm/swarm-tutorial/drain-node.md

@@ -31,16 +31,16 @@ run your manager node. For example, the tutorial uses a machine named
     $ docker node ls
 
     ID               NAME      MEMBERSHIP  STATUS  AVAILABILITY  MANAGER STATUS  LEADER
-  1x2bldyhie1cj    worker1   Accepted    Ready   Active
-  1y3zuia1z224i    worker2   Accepted    Ready   Active
-  2p5bfd34mx4op *  manager1  Accepted    Ready   Active        Reachable       Yes
+    1x2bldyhie1cj    worker1   Accepted    Ready   Active
+    1y3zuia1z224i    worker2   Accepted    Ready   Active
+    2p5bfd34mx4op *  manager1  Accepted    Ready   Active        Reachable       Yes
     ```
 
 2. If you aren't still running the `redis` service from the [rolling
 update](rolling-update.md) tutorial, start it now:
 
     ```bash
-    $ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
+    $ docker service create --replicas 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
 
     69uh57k8o03jtqj9uvmteodbb
     ```
@@ -50,6 +50,7 @@ tasks to different nodes:
 
     ```
     $ docker service tasks redis
+
     ID                         NAME     SERVICE  IMAGE        LAST STATE          DESIRED STATE  NODE
     3wfqsgxecktpwoyj2zjcrcn4r  redis.1  redis    redis:3.0.6  RUNNING 13 minutes  RUNNING        worker2
     8lcm041z3v80w0gdkczbot0gg  redis.2  redis    redis:3.0.6  RUNNING 13 minutes  RUNNING        worker1
@@ -59,7 +60,7 @@ tasks to different nodes:
     In this case the Swarm manager distributed one task to each node. You may
     see the tasks distributed differently among the nodes in your environment.
 
-4. Run `docker node update --availability drain NODE-ID` to drain a node that
+4. Run `docker node update --availability drain <NODE-ID>` to drain a node that
 had a task assigned to it:
 
     ```bash
@@ -95,8 +96,8 @@ task assignments for the `redis` service:
     with `Drain` availability and creating a new task on a node with `Active`
     availability.
 
-7. Run  `docker node update --availability active NODE-ID` to return the drained
-node to an active state:
+7. Run  `docker node update --availability active <NODE-ID>` to return the
+drained node to an active state:
 
     ```bash
     $ docker node update --availability active worker1
@@ -122,8 +123,4 @@ node to an active state:
   * when you set another node to `Drain` availability
   * when a task fails on another active node
 
-## What's next?
-
-The next topic in the tutorial introduces volumes.
-
 <p style="margin-bottom:300px">&nbsp;</p>

docs/swarm/swarm-tutorial/inspect-service.md

@@ -20,10 +20,11 @@ the Docker CLI to see details about the service running in the Swarm.
 run your manager node. For example, the tutorial uses a machine named
 `manager1`.
 
-2. Run `docker service inspect --pretty SERVICE-ID` to display the details about
-a service in an easily readable format.
+2. Run `docker service inspect --pretty <SERVICE-ID>` to display the details
+about a service in an easily readable format.
 
     To see the details on the `helloworld` service:
+
     ```
     $ docker service inspect --pretty helloworld
 
@@ -33,7 +34,7 @@ a service in an easily readable format.
      Scale:	1
     Placement:
      Strategy:	SPREAD
-    UpateConfig:
+    UpdateConfig:
      Parallelism:	1
     ContainerSpec:
      Image:		alpine
@@ -85,7 +86,7 @@ a service in an easily readable format.
     ]
     ```
 
-4. Run `docker service tasks SERVICE-ID` to see which nodes are running the
+4. Run `docker service tasks <SERVICE-ID>` to see which nodes are running the
 service:
 
     ```

docs/swarm/swarm-tutorial/rolling-update.md

@@ -25,7 +25,7 @@ run your manager node. For example, the tutorial uses a machine named
 the swarm to update one node every 10 seconds:
 
     ```bash
-    $ docker service create --scale 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
+    $ docker service create --replicas 3 --name redis --update-delay 10s --update-parallelism 1 redis:3.0.6
 
     8m228injfrhdym2zvzhl9k3l0
     ```
@@ -35,12 +35,13 @@ the swarm to update one node every 10 seconds:
     The `--update-parallelism` flag configures the number of service tasks
     to update simultaneously.
 
-    The `--update-delay` flag configures the time delay between updates to
-    a service task or sets of tasks. You can describe the time `T` in the number
-    of seconds `Ts`, minutes `Tm`, or hours `Th`. So `10m` indicates a 10 minute
-    delay.
+    The `--update-delay` flag configures the time delay between updates to a
+    service task or sets of tasks. You can describe the time `T` as a
+    combination of the number of seconds `Ts`, minutes `Tm`, or hours `Th`. So
+    `10m30s` indicates a 10 minute 30 second delay.
 
 3. Inspect the `redis` service:
+
     ```
     $ docker service inspect redis --pretty
 
@@ -50,7 +51,7 @@ the swarm to update one node every 10 seconds:
      Scale:	3
     Placement:
      Strategy:	SPREAD
-    UpateConfig:
+    UpdateConfig:
      Parallelism:	1
      Delay:		10s
     ContainerSpec:
@@ -84,7 +85,7 @@ desired state:
    Image:		redis:3.0.7
    ```
 
-6. Run `docker service tasks TASK-ID` to watch the rolling update:
+6. Run `docker service tasks <TASK-ID>` to watch the rolling update:
 
     ```
     $ docker service tasks redis

docs/swarm/swarm-tutorial/scale-service.md

@@ -24,19 +24,19 @@ run your manager node. For example, the tutorial uses a machine named
 2. Run the following command to change the desired state of the
 service runing in the Swarm:
 
-    ```
-    $ docker service update --scale NUMBER-OF-TASKS SERVICE-ID
+    ```bash
+    $ docker service update --replicas <NUMBER-OF-TASKS> <SERVICE-ID>
     ```
 
-    The `--scale` flag indicates the number of tasks you want in the new desired
-    state. For example:
+    The `--replicas` flag indicates the number of tasks you want in the new
+    desired state. For example:
 
-    ```
-    $ docker service update --scale 5 helloworld
+    ```bash
+    $ docker service update --replicas 5 helloworld
     helloworld
     ```
 
-3. Run `docker service tasks SERVICE-ID` to see the updated task list:
+3. Run `docker service tasks <SERVICE-ID>` to see the updated task list:
 
     ```
     $ docker service tasks helloworld