Merge pull request #1982 from londoncalling/vote-tutorial-feedback

feedback on PowerShell env setup, clarified env vs. ssh

engine/getstarted-voting-app/node-setup.md

@@ -18,6 +18,8 @@ run some basic commmands to interact with the machines.
 [Docker Machine](/machine/get-started.md) (`docker-machine`), which
 comes auto-installed with both Docker for Mac and Docker for Windows.
 
+<p />
+
 * **VirtualBox driver on Docker for Mac** - On Docker for Mac, you'll
 use `docker-machine` with the `virtualbox` driver to create machines. If you had
 a legacy installation of Docker Toolbox, you already have Oracle VirtualBox
@@ -29,7 +31,7 @@ using the Toolbox installer because it can
 here](https://www.virtualbox.org/wiki/Downloads), and follow install
 instructions. You do not need to start VirtualBox. The `docker-machine create`
 command will call it via the driver.
-
+<p />
 * **Hyper-V driver on Docker for Windows** - On Docker for Windows, you
 will use `docker-machine` with the [`Hyper-V`](/machine/drivers/hyper-v/) driver
 to create machines. You will need to follow the instructions in the [Hyper-V
@@ -40,7 +42,8 @@ in an elevated PowerShell per those instructions.
 
 ### Commands to create machines
 
-The Docker Machine commands to create local virtual machines on Mac and Windows are are as follows. The rest of the `docker-machine` commands are the same on both.
+The Docker Machine commands to create local virtual machines on Mac and Windows
+are are as follows.
 
 #### Mac
 
@@ -118,11 +121,20 @@ You will need the IP address of the manager for a later step.
 
 ## Interacting with the machines
 
-There are several ways to interact with these machines directly on the command line or programatically. We'll cover two methods for managing the machines directly from the command line:
+There are a few ways to interact with these machines directly on the command
+line or programatically. We'll cover two methods for managing the machines
+directly from the command line:
+
+* [Manage the machines from a pre-configured shell](#manage-the-machines-from-a-pre-configured-shell)
+
+* [`docker ssh` into a machine](#ssh-into-a-machine)
 
 #### Manage the machines from a pre-configured shell
 
-You can use `docker-machine` to set up environment variables in a shell that connect to the Docker client on a virtual machine. With this setup, the Docker commands you type in your local shell will run on the given machine. We'll set up a shell to talk to our manager machine.
+You can use `docker-machine` to set up environment variables in a shell that
+connect to the Docker client on a virtual machine. With this setup, the Docker
+commands you type in your local shell will run on the given machine. As an
+example, we'll set up a shell to talk to our manager machine.
 
 1.  Run `docker-machine env manager` to get environment variables for the manager.
 
@@ -138,15 +150,22 @@ You can use `docker-machine` to set up environment variables in a shell that con
     ```
 
 2.  Connect your shell to the manager.
+
+    On Mac:
+
     ```
     $ eval $(docker-machine env manager)
     ```
 
-    This sets environment variables for the current shell that the Docker client will read which specify the TLS settings.
+    On Windows PowerShell:
 
-    **Note**: If you are using `fish`, or a Windows shell such as
-    Powershell/`cmd.exe` the above method will not work as described.
-    Instead, see the [env command reference documentation](/machine/reference/env.md) to learn how to set the environment variables for your shell.
+    ```
+    & docker-machine.exe env manager | Invoke-Expression
+    ```
+
+    This sets [environment variables](/machine/reference/env.md) for the current
+shell. The rest of the `docker-machine` commands we cover are the same on both
+Mac and Windows.
 
 3.  Run `docker-machine ls` again.
 
@@ -157,11 +176,19 @@ You can use `docker-machine` to set up environment variables in a shell that con
     worker    -        virtualbox   Running   tcp://192.168.99.101:2376           v1.13.0-rc6   
     ```
 
-    The asterisk next `manager` indicates that the current shell is connected to that machine. Docker commands run in this shell will execute on the `manager.` (Note that you could change this by re-running the above commands to connect to the `worker`, or open multiple terminals to talk to multiple machines.)
+    The asterisk next `manager` indicates that the current shell is connected to
+that machine. Docker commands run in this shell will execute on the `manager.`
+(Note that you could change this by re-running the above commands to connect to
+the `worker`, or open multiple terminals to talk to multiple machines.)
+
+If you use this method, you'll need to re-configure the environment setup each
+time you want to switch between the manager and the worker, or keep two shells
+open.
 
 #### ssh into a machine
 
-You can use the command `docker-machine ssh <MACHINE-NAME>` to log into a machine:
+Alternatively, you can use the command `docker-machine ssh <MACHINE-NAME>` to
+log into a machine.
 
 ```
 $ docker-machine ssh manager
@@ -185,7 +212,13 @@ Boot2Docker version 1.13.0-rc6, build HEAD : 5ab2289 - Wed Jan 11 23:37:52 UTC 2
 Docker version 1.13.0-rc6, build 2f2d055
 ```
 
-We'll use this method later in the example.
+You _do not_ have to set up `docker-machine` environment variables, as in the
+previous section, for `docker ssh` to work. You can run this command in that
+same shell you configured to talk to the manager, or in a new one, and it will
+work either way.
+
+This tutorial will employ the `docker ssh` method to run commands on the
+machines, but which approach you use is really a matter of personal preference.
 
 ## What's next?
 

engine/getstarted-voting-app/test-drive.md

@@ -20,7 +20,7 @@ Click on either cats or dogs to vote.
 
 ## View the results tally
 
-Now, go to `<MANAGER-IP:>5001` in a web browser to view the voting results tally, as one might do in the role of poll coordinator. The tally is shown by percentage in the current configuration of the app.
+Now, go to `MANAGER-IP:5001` in a web browser to view the voting results tally, as one might do in the role of poll coordinator. The tally is shown by percentage in the current configuration of the app.
 
 ![Results web page](images/vote-results.png)