diff --git a/docs/reference/config.md b/docs/reference/config.md
index 61f5bc65b2..5c96aef82a 100644
--- a/docs/reference/config.md
+++ b/docs/reference/config.md
@@ -10,7 +10,19 @@ parent="smn_machine_subcmds"
 
 # config
 
-Show the Docker client configuration for a machine.
+    Usage: docker-machine config [OPTIONS] [arg...]
+
+    Print the connection config for machine
+
+    Description:
+       Argument is a machine name.
+
+    Options:
+
+       --swarm      Display the Swarm config instead of the Docker daemon
+
+
+For example: 
 
     $ docker-machine config dev
     --tlsverify
diff --git a/docs/reference/help.md b/docs/reference/help.md
index 365966739e..ce87bffa3d 100644
--- a/docs/reference/help.md
+++ b/docs/reference/help.md
@@ -10,8 +10,22 @@ parent="smn_machine_subcmds"
 
 # help
 
+    Usage: docker-machine help [arg...]
+
+    Shows a list of commands or help for one command
+
 Usage: docker-machine help _subcommand_
 
-Show help text, for example:
+For example:
 
     $ docker-machine help config
+    Usage: docker-machine config [OPTIONS] [arg...]
+
+    Print the connection config for machine
+
+    Description:
+       Argument is a machine name.
+
+    Options:
+
+       --swarm      Display the Swarm config instead of the Docker daemon
diff --git a/docs/reference/kill.md b/docs/reference/kill.md
index b1258cc33f..a4b71234c4 100644
--- a/docs/reference/kill.md
+++ b/docs/reference/kill.md
@@ -11,7 +11,14 @@ parent="smn_machine_subcmds"
 
 # kill
 
-Kill (abruptly force stop) a machine.
+    Usage: docker-machine kill [arg...]
+
+    Kill (abruptly force stop) a machine
+
+    Description:
+       Argument(s) are one or more machine names.
+
+For example:
 
     $ docker-machine ls
     NAME   ACTIVE   DRIVER       STATE     URL
diff --git a/docs/reference/ls.md b/docs/reference/ls.md
index 83a4c90cae..70c8a59323 100644
--- a/docs/reference/ls.md
+++ b/docs/reference/ls.md
@@ -18,7 +18,7 @@ parent="smn_machine_subcmds"
 
        --quiet, -q                                  Enable quiet mode
        --filter [--filter option --filter option]   Filter output based on conditions provided
-       --timeout, -t                                Timeout in seconds, default to 10s
+       --timeout, -t "10"                           Timeout in seconds, default to 10s
        --format, -f                                 Pretty-print machines using a Go template
 
 ## Timeout
@@ -102,7 +102,7 @@ for all running machines:
 
 To list all machine names with their driver in a table format you can use:
 
-    $ docker-machine ls --format "table {{.Name}}: {{.DriverName}}"
+    $ docker-machine ls --format "table {{.Name}} {{.DriverName}}"
     NAME     DRIVER
     default  virtualbox
     ec2      amazonec2
diff --git a/docs/reference/regenerate-certs.md b/docs/reference/regenerate-certs.md
index f9cf67b47b..52ba928427 100644
--- a/docs/reference/regenerate-certs.md
+++ b/docs/reference/regenerate-certs.md
@@ -10,8 +10,21 @@ parent="smn_machine_subcmds"
 
 # regenerate-certs
 
+    Usage: docker-machine regenerate-certs [OPTIONS] [arg...]
+
+    Regenerate TLS Certificates for a machine
+
+    Description:
+       Argument(s) are one or more machine names.
+
+    Options:
+
+       --force, -f  Force rebuild and do not prompt
+
 Regenerate TLS certificates and update the machine with new certs.
 
+For example: 
+
     $ docker-machine regenerate-certs dev
     Regenerate TLS machine certs?  Warning: this is irreversible. (y/n): y
     Regenerating TLS certificates
diff --git a/docs/reference/restart.md b/docs/reference/restart.md
index 91a5a49b30..013a04b7bc 100644
--- a/docs/reference/restart.md
+++ b/docs/reference/restart.md
@@ -11,6 +11,13 @@ parent="smn_machine_subcmds"
 
 # restart
 
+    Usage: docker-machine restart [arg...]
+
+    Restart a machine
+
+    Description:
+       Argument(s) are one or more machine names.
+       
 Restart a machine. Oftentimes this is equivalent to
 `docker-machine stop; docker-machine start`. But some cloud driver try to implement a clever restart which keeps the same
 ip address.
diff --git a/docs/reference/start.md b/docs/reference/start.md
index eb37f5e073..9c8e22137f 100644
--- a/docs/reference/start.md
+++ b/docs/reference/start.md
@@ -11,7 +11,14 @@ parent="smn_machine_subcmds"
 
 # start
 
-Start a machine.
+    Usage: docker-machine start [arg...]
+
+    Start a machine
+
+    Description:
+       Argument(s) are one or more machine names.
+
+For example:
 
     $ docker-machine start dev
     Starting VM...
diff --git a/docs/reference/status.md b/docs/reference/status.md
index c94eafdcc0..4e44e619d7 100644
--- a/docs/reference/status.md
+++ b/docs/reference/status.md
@@ -10,7 +10,14 @@ parent="smn_machine_subcmds"
 
 # status
 
-Get the status of a machine.
+    Usage: docker-machine status [arg...]
+
+    Get the status of a machine
+
+    Description:
+       Argument is a machine name.
+
+For example:
 
     $ docker-machine status dev
     Running
diff --git a/docs/reference/stop.md b/docs/reference/stop.md
index 41a8f9604d..1d4fb25ec8 100644
--- a/docs/reference/stop.md
+++ b/docs/reference/stop.md
@@ -11,7 +11,14 @@ parent="smn_machine_subcmds"
 
 # stop
 
-Gracefully stop a machine.
+    Usage: docker-machine stop [arg...]
+
+    Gracefully Stop a machine
+
+    Description:
+       Argument(s) are one or more machine names.
+
+For example:
 
     $ docker-machine ls
     NAME   ACTIVE   DRIVER       STATE     URL