Merge pull request #1035 from londoncalling/docker-cloud-cli-install

clarify docker-cloud install

docker-cloud/getting-started/deploy-app/2_set_up.md

@@ -13,19 +13,36 @@ In this step you install the Docker Cloud CLI so interact with the service using
 
 Install the docker-cloud CLI using the package manager for your system.
 
-#### Install using a Docker container
+#### Run the CLI in a Docker container
 
-If you have Docker Engine installed locally, you can run the following `docker` command in your shell regardless of which operating system you are using.
+If you have Docker Engine installed locally, you can run the following `docker`
+command in your shell regardless of which operating system you are using.
 
 ```none
 docker run dockercloud/cli -h
 ```
 
-The command runs a container that installs the separate `docker-cloud` CLI for you. Learn more about this container [here](https://github.com/docker/dockercloud-cli#docker-image).
+This command runs the `docker-cloud` CLI image in a container for you. Learn
+more about how to use this container
+[here](https://github.com/docker/dockercloud-cli#docker-image).
 
 #### Install for Linux or Windows
 
-Open your shell or terminal application and execute the following command:
+You can install the CLI locally using the [pip](https://pip.pypa.io/en/stable/)
+package manager, which is a package manager for
+[Python](https://www.python.org/) applications.
+
+* If you already have 2.x or Python 3.x installed, you probably have `pip` and
+`setuptools`, but will need to upgrade per the instructions
+[here](https://packaging.python.org/installing/).
+
+* If you do not have Python or `pip` installed, you can either [install
+Python](https://wiki.python.org/moin/BeginnersGuide/Download) or use this
+[standalone pip
+installer](https://pip.pypa.io/en/latest/installing/#installing-with-get-pip-py). You do not need Python for our purposes, just `pip`.
+
+Now that you have `pip`, open a shell or terminal
+window and run the following command to install the docker-cloud CLI:
 
 ```bash
 $ pip install docker-cloud
@@ -41,6 +58,8 @@ Once Homebrew is installed, open Terminal and run the following command:
 $ brew install docker-cloud
 ```
 
+> **Note:** You can also use [pip](https://pip.pypa.io/en/stable/) to install on macOS, but we suggest Homebrew since it is a package manager designed for the Mac.
+
 ## Validate the CLI installation
 Check that the CLI installed correctly, using the `docker-cloud -v` command. (This command is the same for every platform.)
 

docker-cloud/installing-cli.md

@@ -18,38 +18,60 @@ necessary.
 
 Install the docker-cloud CLI either by running a Docker container, or by using the package manager for your system.
 
-#### Install using a Docker container
+#### Run the CLI in a Docker container
 
-If you have Docker Engine installed locally, you can simply run the following command regardless of which operating system you are using.
+If you have Docker Engine installed locally, you can run the following `docker`
+command in your shell regardless of which operating system you are using.
 
 ```none
 docker run dockercloud/cli -h
 ```
 
-This runs a container that installs the docker-cloud CLI for you. Learn more
-about this container
+This command runs the `docker-cloud` CLI image in a container for you. Learn
+more about how to use this container
 [here](https://github.com/docker/dockercloud-cli#docker-image).
 
 #### Install for Linux or Windows
 
-Open your terminal or command shell and execute the following command:
+You can install the CLI locally using the [pip](https://pip.pypa.io/en/stable/)
+package manager, which is a package manager for
+[Python](https://www.python.org/) applications.
+
+* If you already have 2.x or Python 3.x installed, you probably have `pip` and
+`setuptools`, but will need to upgrade per the instructions
+[here](https://packaging.python.org/installing/).
+
+* If you do not have Python or `pip` installed, you can either [install
+Python](https://wiki.python.org/moin/BeginnersGuide/Download) or use this
+[standalone pip
+installer](https://pip.pypa.io/en/latest/installing/#installing-with-get-pip-py). You do not need Python for our purposes, just `pip`.
+
+Now that you have `pip`, open a shell or terminal
+window and run the following command to install the docker-cloud CLI:
 
 ```bash
 $ pip install docker-cloud
 ```
-If you encounter errors on Linux machines, make sure that `python-dev` is installed.
-For example, on Ubuntu, run the following command: `apt-get install python-dev`
+
+If you encounter errors on Linux machines, make sure that `python-dev` is
+installed. For example, on Ubuntu, run the following command: `apt-get install
+python-dev`
 
 #### Install on macOS
 
-We recommend installing Docker CLI for macOS using Homebrew. If you don't have `brew` installed, follow the instructions here: <a href="http://brew.sh" target="_blank">http://brew.sh</a>
+We recommend installing Docker CLI for macOS using Homebrew. If you don't have
+`brew` installed, follow the instructions here: <a href="http://brew.sh"
+target="_blank">http://brew.sh</a>
 
 Once Homebrew is installed, open Terminal and run the following command:
 
 ```bash
 $ brew install docker-cloud
 ```
 
+> **Note:** You can also use [pip](https://pip.pypa.io/en/stable/) to install on macOS, but we suggest Homebrew since it is a package manager designed for the
+Mac.
+
 #### Validate the installation
 
 Check that the CLI installed correctly: