Update docs with better install instructions

There are a few minor fixes and enhancements for things thrown in, too.

Signed-off-by: Nathan LeClaire <nathan.leclaire@gmail.com>

README.md

@@ -1,8 +1,8 @@
 # Docker Machine
 
-Machine makes it really easy to create Docker hosts on your computer, on cloud
-providers and inside your own data center. It creates servers, installs Docker
-on them, then configures the Docker client to talk to them.
+Machine lets you create Docker hosts on your computer, on cloud providers, and
+inside your own data center. It creates servers, installs Docker on them, then
+configures the Docker client to talk to them.
 
 It works a bit like this:
 

docs/index.md

@@ -10,9 +10,9 @@ page_keywords: docker, machine, amazonec2, azure, digitalocean, google, openstac
 > **Note**: Machine is currently in beta, so things are likely to change. We
 > don't recommend you use it in production yet.
 
-Machine makes it really easy to create Docker hosts on your computer, on cloud
-providers and inside your own data center. It creates servers, installs Docker
-on them, then configures the Docker client to talk to them.
+Machine lets you create Docker hosts on your computer, on cloud providers, and
+inside your own data center. It creates servers, installs Docker on them, then
+configures the Docker client to talk to them.
 
 Once your Docker host has been created, it then has a number of commands for
 managing them:
@@ -39,9 +39,9 @@ For more information and resources, please visit
 
 ## Installation
 
-Docker Machine is supported on Windows, OSX, and Linux.  To install Docker
-Machine, download the appropriate binary for your OS and architecture, rename it `docker-machine` and place
-into your `PATH`:
+Docker Machine is supported on Windows, OSX, and Linux and is installable as one
+standalone binary.  The links to the binaries for the various platforms and
+architectures are below:
 
 - [Windows - 32bit](https://github.com/docker/machine/releases/download/v0.1.0/docker-machine_windows-386.exe)
 - [Windows - 64bit](https://github.com/docker/machine/releases/download/v0.1.0/docker-machine_windows-amd64.exe)
@@ -50,17 +50,68 @@ into your `PATH`:
 - [Linux - x86_64](https://github.com/docker/machine/releases/download/v0.1.0/docker-machine_linux-amd64)
 - [Linux - i386](https://github.com/docker/machine/releases/download/v0.1.0/docker-machine_linux-386)
 
+### OSX and Linux
+
+To install on OSX or Linux, download the proper binary to somewhere in your
+`PATH` (e.g. `/usr/local/bin`) and make it executable.  For instance, to install on
+most OSX machines these commands should suffice:
+
+```
+$ curl https://github.com/docker/machine/releases/download/v0.1.0/docker-machine_darwin-amd64 > /usr/local/bin/docker-machine
+$ chmod +x /usr/local/bin/docker-machine
+```
+
+For Linux, just substitute "linux" for "darwin" in the binary name above.
+
 Now you should be able to check the version with `docker-machine -v`:
 
 ```
 $ docker-machine -v
 machine version 0.2.0
 ```
 
+In order to run Docker commands on your machines without having to use SSH, make
+sure to install the Docker client as well, e.g.:
+
+```
+$ curl https://get.docker.com/builds/Darwin/x86_64/docker-latest > /usr/local/bin/docker
+```
+
+### Windows
+
+Currently, Docker recommends that you install and use Docker Machine on Windows
+with [msysgit](https://msysgit.github.io/).  This will provide you with some
+programs that Docker Machine relies on such as `ssh`, as well as a functioning
+shell.
+
+When you have installed msysgit, start up the terminal prompt and run the
+following commands.  Here it is assumed that you are on a 64-bit Windows
+installation.  If you are on a 32-bit installation, please substitute "i386" for
+"x86_64" in the URLs mentioned.
+
+First, install the Docker client binary:
+
+```
+curl https://get.docker.com/builds/Windows/x86_64/docker-latest > /bin/docker
+```
+
+Next, install the Docker Machine binary:
+
+```
+curl https://github.com/docker/machine/releases/docker-machine_windows-amd64.exe > /bin/docker-machine
+```
+
+Now running `docker-machine` should work.
+
+```
+$ docker-machine -v
+machine version 0.1.0
+```
+
 ## Getting started with Docker Machine using a local VM
 
-Let's take a look at using `docker-machine` to creating, using, and managing a Docker
-host inside of [VirtualBox](https://www.virtualbox.org/).
+Let's take a look at using `docker-machine` for creating, using, and managing a
+Docker host inside of [VirtualBox](https://www.virtualbox.org/).
 
 First, ensure that
 [VirtualBox 4.3.26](https://www.virtualbox.org/wiki/Downloads) is correctly
@@ -78,7 +129,7 @@ To create one, we run the `docker-machine create` command, passing the string
 `virtualbox` to the `--driver` flag.  The final argument we pass is the name of
 the machine - in this case, we will name our machine "dev".
 
-This will download a lightweight Linux distribution
+This command will download a lightweight Linux distribution
 ([boot2docker](https://github.com/boot2docker/boot2docker)) with the Docker
 daemon installed, and will create and start a VirtualBox VM with Docker running.
 
@@ -148,11 +199,51 @@ $ docker-machine ip
 192.168.99.100
 ```
 
-Now you can manage as many local VMs running Docker as you please- just run
-`docker-machine create` again.
+For instance, you can try running a webserver ([nginx](https://nginx.org)) in a
+container with the following command:
+
+```
+$ docker run -d -p 8000:80 nginx
+```
+
+When the image is finished pulling, you can hit the server at port 8000 on the
+IP address given to you by `docker-machine ip`.  For instance:
+
+```
+$ curl $(docker-machine ip dev):8000
+<!DOCTYPE html>
+<html>
+<head>
+<title>Welcome to nginx!</title>
+<style>
+    body {
+        width: 35em;
+        margin: 0 auto;
+        font-family: Tahoma, Verdana, Arial, sans-serif;
+    }
+</style>
+</head>
+<body>
+<h1>Welcome to nginx!</h1>
+<p>If you see this page, the nginx web server is successfully installed and
+working. Further configuration is required.</p>
+
+<p>For online documentation and support please refer to
+<a href="http://nginx.org/">nginx.org</a>.<br/>
+Commercial support is available at
+<a href="http://nginx.com/">nginx.com</a>.</p>
+
+<p><em>Thank you for using nginx.</em></p>
+</body>
+</html>
+```
+
+You can create and manage as many local VMs running Docker as you please- just
+run `docker-machine create` again.  All created machines will appear in the
+output of `docker-machine ls`.
 
-If you are finished using a host, you can stop it with `docker stop` and start
-it again with `docker start`:
+If you are finished using a host for the time being, you can stop it with
+`docker stop` and later start it again with `docker start`:
 
 ```
 $ docker-machine stop
@@ -171,13 +262,14 @@ $ docker-machine start dev
 
 ## Using Docker Machine with a cloud provider
 
-One of the nice things about `docker-machine` is that it provides several “drivers”
-which let you use the same interface to create hosts on many different cloud
-platforms.  This is accomplished by using the `docker-machine create` command with the
- `--driver` flag.  Here we will be demonstrating the
-[Digital Ocean](https://digitalocean.com) driver (called `digitalocean`), but
-there are drivers included for several providers including Amazon Web Services,
-Google Compute Engine, and Microsoft Azure.
+Creating a local virtual machine running Docker is useful and fun, but it is not
+the only thing Docker Machine is capable of.  Docker Machine supports several
+“drivers” which let you use the same interface to create hosts on many different
+cloud or local virtualization platforms.  This is accomplished by using the
+`docker-machine create` command with the `--driver` flag.  Here we will be
+demonstrating the [Digital Ocean](https://digitalocean.com) driver (called
+`digitalocean`), but there are drivers included for several providers including
+Amazon Web Services, Google Compute Engine, and Microsoft Azure.
 
 Usually it is required that you pass account verification credentials for these
 providers as flags to `docker-machine create`.  These flags are unique for each driver.
@@ -188,8 +280,7 @@ Let's take a look at how to do this.
 
 To generate your access token:
 
-1. Go to the Digital Ocean administrator panel and click on "Apps and API" in
-the side panel.
+1. Go to the Digital Ocean administrator console and click on "API" in the header.
 2. Click on "Generate New Token".
 3. Give the token a clever name (e.g. "machine"), make sure the "Write" checkbox
 is checked, and click on "Generate Token".
@@ -213,25 +304,25 @@ INFO[0085] "staging" has been created and is now the active machine
 INFO[0085] To point your Docker client at it, run this in your shell: eval "$(docker-machine env staging)"
 ```
 
-For convenience, `docker-machine` will use sensible defaults for choosing settings such
- as the image that the VPS is based on, but they can also be overridden using
-their respective flags (e.g. `--digitalocean-image`).  This is useful if, for
-instance, you want to create a nice large instance with a lot of memory and CPUs
-(by default `docker-machine` creates a small VPS).  For a full list of the
-flags/settings available and their defaults, see the output of
+For convenience, `docker-machine` will use sensible defaults for choosing
+settings such as the image that the VPS is based on, but they can also be
+overridden using their respective flags (e.g. `--digitalocean-image`).  This is
+useful if, for instance, you want to create a nice large instance with a lot of
+memory and CPUs (by default `docker-machine` creates a small VPS).  For a full
+list of the flags/settings available and their defaults, see the output of
 `docker-machine create -h`.
 
 When the creation of a host is initiated, a unique SSH key for accessing the
 host (initially for provisioning, then directly later if the user runs the
-`docker-machine ssh` command) will be created automatically and stored in the client's
-directory in `~/.docker/machines`.  After the creation of the SSH key, Docker
-will be installed on the remote machine and the daemon will be configured to
-accept remote connections over TCP using TLS for authentication.  Once this
+`docker-machine ssh` command) will be created automatically and stored in the
+client's directory in `~/.docker/machines`.  After the creation of the SSH key,
+Docker will be installed on the remote machine and the daemon will be configured
+to accept remote connections over TCP using TLS for authentication.  Once this
 is finished, the host is ready for connection.
 
 And then from this point, the remote host behaves much like the local host we
-created in the last section. If we look at `docker-machine`, we’ll see it is now the
-active host:
+created in the last section. If we look at `docker-machine`, we’ll see it is now
+the active host:
 
 ```
 $ docker-machine active dev