WIP:Clarify how to use d4mac, d4win with Swarm mode

updated d4mac, d4win clarification per Charles's comments

copyedits and streamline wording

fixed links

streamlined, fixed line wraps

incorporated more review comments

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

incorporated more review comments

incorporated more edit comments and fixed line wraps

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

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

@@ -25,6 +25,12 @@ node. For example, the tutorial uses a machine named `manager1`.
     docker swarm init --advertise-addr <MANAGER-IP>
     ```
 
+    >**Note:** If you are using Docker for Mac or Docker for Windows to test
+single-node swarm, simply run `docker swarm init` with no arguments. There is no
+need to specify ` --advertise-addr` in this case. To learn more, see the topic
+on how to [Use Docker for Mac or Docker for
+Windows](index.md#use-docker-for-mac-or-docker-for-windows) with Swarm.
+
     In the tutorial, the following command creates a swarm on the `manager1`
     machine:
 

docs/swarm/swarm-tutorial/index.md

@@ -27,7 +27,7 @@ This tutorial uses Docker Engine CLI commands entered on the command line of a
 terminal window. You should be able to install Docker on networked machines and
 be comfortable running commands in the shell of your choice.
 
-If you’re brand new to Docker, see [About Docker Engine](../../index.md).
+If you are brand new to Docker, see [About Docker Engine](../../index.md).
 
 ## Set up
 
@@ -48,37 +48,78 @@ provider. This tutorial uses the following machine names:
 * worker1
 * worker2
 
-###  Docker Engine 1.12 or later
+>**Note:** You can follow many of the tutorial steps to test single-node swarm
+as well, in which case you need only one host. Multi-node commands will not
+work, but you can initialize a swarm, create services, and scale them.
 
-To use swarm mode, you must [install Docker Engine](../../installation/index.md)
-on each one of the host machines. Alternatively, install the latest Docker for
-Mac or Docker for Windows.
+###  Docker Engine 1.12 or newer
 
->**Note**: Docker for Mac and Docker for Windows let you use single-node
-features of swarm mode, like creating a swarm and creating a service. Multi-node
-features like joining additional nodes and scaling a service are not available.
+This tutorial requires Docker Engine 1.12 or newer on each of the host machines.
+Install Docker Engine and verify that the Docker Engine daemon is running on
+each of the machines. You can get the latest version of Docker Engine as
+follows:
 
-Verify that the Docker Engine daemon is running on each of the machines.
+* [install Docker Engine on Linux machines](#install-docker-engine-on-linux-machines)
+
+* [use Docker for Mac or Docker for Windows](#use-docker-for-mac-or-docker-for-windows)
+
+#### Install Docker Engine on Linux machines
+
+If you are using Linux based physical computers or cloud-provided computers as
+hosts, simply follow the [Linux install
+instructions](../../installation/index.md) for your platform. Spin up the three
+machines, and you are ready. You can test both
+single-node and multi-node swarm scenarios on Linux machines.
+
+#### Use Docker for Mac or Docker for Windows
+
+Alternatively, install the latest [Docker for Mac](/docker-for-mac/index.md) or
+[Docker for Windows](/docker-for-windows/index.md) application on a one
+computer. You can test both single-node and multi-node swarm from this computer,
+but you will need to use Docker Machine to test the multi-node scenarios.
+
+* You can use Docker for Mac or Windows to test _single-node_ features of swarm
+mode, including initializing a swarm with a single node, creating services,
+and scaling services. Docker "Moby" on Hyperkit (Mac) or Hyper-V (Windows)
+will serve as the single swarm node.
+
+<br /><br />
+* Currently, you cannot use Docker for Mac or Windows alone to test a
+_multi-node_ swarm. However, you can use the included version of [Docker
+Machine](/machine/overview.md) to create the swarm nodes, then follow the
+tutorial for all multi-node features. For this scenario, you run commands from
+a Docker for Mac or Docker for Windows host, but that Docker host itself is
+_not_ participating in the swarm (i.e., it will not be `manager1`, `worker1`,
+or `worker2` in our example). After you create the nodes, you can run all
+swarm commands as shown from the Mac terminal or Windows PowerShell with
+Docker for Mac or Docker for Windows running.
 
 ### The IP address of the manager machine
 
-The IP address must be assigned to an a network interface available to the host
-operating system. All nodes in the swarm must be able to access the manager at the IP address.
+The IP address must be assigned to a network interface available to the host
+operating system. All nodes in the swarm must be able to access the manager at
+the IP address.
 
 Because other nodes contact the manager node on its IP address, you should use a
 fixed IP address.
 
->**Tip**: You can run `ifconfig` on Linux or Mac OS X to see a list of the
+You can run `ifconfig` on Linux or Mac OS X to see a list of the
 available network interfaces.
 
+If you are using Docker Machine, you can get the manager IP with either
+`docker-machine ls` or `docker-machine ip <MACHINE-NAME>` &#8212; for example,
+`docker-machine ip manager1`.
+
 The tutorial uses `manager1` : `192.168.99.100`.
 
 ### Open ports between the hosts
 
+The following ports must be available. On some systems, these ports are open by default.
+
 * **TCP port 2377** for cluster management communications
 * **TCP** and **UDP port 7946** for communication among nodes
 * **TCP** and **UDP port 4789** for overlay network traffic
 
 ## What's next?
 
-After you have set up your environment, you're ready to [create a swarm](create-swarm.md).
+After you have set up your environment, you are ready to [create a swarm](create-swarm.md).