From eabe07294d9c3e2f8dd901420a96dc63db5f3f27 Mon Sep 17 00:00:00 2001
From: Nathan LeClaire <nathan.leclaire@gmail.com>
Date: Mon, 6 Jul 2015 16:46:15 -0700
Subject: [PATCH] Fix some docs issues

Signed-off-by: Nathan LeClaire <nathan.leclaire@gmail.com>
---
 docs/index.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 17a47ec0b3..6410c64dd6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -548,23 +548,23 @@ The following is an example usage:
 $ docker-machine create -d virtualbox \
     --engine-label foo=bar \
     --engine-label spam=eggs \
-    --engine-storage-driver devicemapper \
+    --engine-storage-driver overlay \
     --engine-insecure-registry registry.myco.com \
     foobarmachine
 ```
 
 This will create a virtual machine running locally in Virtualbox which uses the
-`devicemapper` storage backend, has the key-value pairs `foo=bar` and
-`spam=eggs` as labels on the engine, and allows pushing / pulling from the
-insecure registry located at `registry.myco.com`. You can verify much of this
-by inspecting the output of `docker info`:
+`overlay` storage backend, has the key-value pairs `foo=bar` and `spam=eggs` as
+labels on the engine, and allows pushing / pulling from the insecure registry
+located at `registry.myco.com`. You can verify much of this by inspecting the
+output of `docker info`:
 
 ```
 $ eval $(docker-machine env foobarmachine)
 $ docker version
 Containers: 0
 Images: 0
-Storage Driver: devicemapper
+Storage Driver: overlay
 ...
 Name: foobarmachine
 ...
@@ -1007,7 +1007,8 @@ $ cat foo.txt
 A file created remotely!
 ```
 
-Files are copied recursively by default (`scp`'s `-r` flag).
+Just like how `scp` has a `-r` flag for copying files recursively,
+`docker-machine` has a `-r` flag for this feature.
 
 In the case of transferring files from machine to machine, they go through the
 local host's filesystem first (using `scp`'s `-3` flag).
@@ -1037,11 +1038,14 @@ dev    *        virtualbox   Stopped
 
 #### upgrade
 
-Upgrade a machine to the latest version of Docker. If the machine uses Ubuntu
-as the underlying operating system, it will upgrade the package `lxc-docker`
-(our recommended install method). If the machine uses boot2docker, this command
-will download the latest boot2docker ISO and replace the machine's existing ISO
-with the latest.
+Upgrade a machine to the latest version of Docker. How this upgrade happens
+depends on the underlying distribution used on the created instance.
+
+For example, if the machine uses Ubuntu as the underlying operating system, it
+will run a command similar to `sudo apt-get upgrade lxc-docker`, because Machine
+expects Ubuntu machines it manages to use this package. As another example, if
+the machine uses boot2docker for its OS, this command will download the latest
+boot2docker ISO and replace the machine's existing ISO with the latest.
 
 ```
 $ docker-machine upgrade dev