docs(*): clarify clusters:create options

The documentation around clusters:create was confusing. This commit
adds more information in both the README and the CLI's help option
for clusters:create.

closes #959

Author: carmstrong

README.md

@@ -132,6 +132,12 @@ Initialize a `dev` cluster with a list of CoreOS hosts and your CoreOS private k
 $ deis clusters:create dev local.deisapp.com --hosts=local.deisapp.com --auth=~/.vagrant.d/insecure_private_key
 ```
 
+The parameters to `deis clusters:create` are:
+* cluster name (`dev`) - the name used by Deis to reference the cluster
+* cluster hostname (`local.deisapp.com`) - the hostname under which apps are created, like `balancing-giraffe.local.deisapp.com`
+* cluster members (`--hosts`) - a comma-separated list of cluster members -- not necessarily all members, but at least one (for EC2 and Rackspace, this is a list of the internal IPs like `--hosts=10.21.12.1,10.21.12.2,10.21.12.3`)
+* auth SSH key (`--auth`) - the SSH private key used to provision servers (for EC2 and Rackspace, this key is likely `~/.ssh/deis`)
+
 The `dev` cluster will be used as the default cluster for future `deis` commands.
 
 # Usage

client/deis.py

@@ -797,6 +797,13 @@ def clusters_create(self, args):
 
         Usage: deis clusters:create <id> <domain> --hosts=<hosts> --auth=<auth> [options]
 
+        Parameters:
+
+        <id>             a name for the cluster
+        <domain>         a domain under which app hostnames will live
+        <hosts>          a comma-separated list of cluster members
+        <auth>           a path to an SSH private key used to connect to cluster members
+
         Options:
 
         --type=TYPE      cluster type [default: coreos]