Improve ks init help message

Specifically,

1. Place more emphasize on project initialization based on context
2. Place ksonnet-lib details into footer.
3. Order examples based on most common use cases.
4. Suggest to visit ks generate

cmd/init.go

@@ -36,7 +36,7 @@ func init() {
 
 var initCmd = &cobra.Command{
 	Use:   "init <app-name>",
-	Short: "Initialize a ksonnet project",
+	Short: "Initialize a ksonnet application",
 	RunE: func(cmd *cobra.Command, args []string) error {
 		flags := cmd.Flags()
 		if len(args) != 1 {
@@ -77,39 +77,56 @@ var initCmd = &cobra.Command{
 
 		return c.Run()
 	},
-	Long: `Initialize a ksonnet project in a new directory,` + " `app-name`" + `. This process
-consists of two steps:
-
-1. Generating ksonnet-lib. Users can set flags to generate the library based on
-   a variety of data, including server configuration and an OpenAPI
-   specification of a Kubernetes build. By default, this is generated from the
-   capabilities of the cluster specified in the cluster of the current context
-   specified in` + " `$KUBECONFIG`" + `.
-2. Generating the following tree in the current directory.
-
-        app-name/
-          .gitignore     Default .gitignore; can customize VCS
-          .ksonnet/      Metadata for ksonnet
-          environments/
-            default/      [Default generated environment]
-          components/    Top-level Kubernetes objects defining application
-          lib/           user-written .libsonnet files
-          vendor/        part libraries, prototypes
+	Long: `Initialize a ksonnet application in a new directory,` + " `app-name`" + `.
+
+This command generates all the project scaffolding required to begin creating and
+deploying components to Kubernetes clusters.
+
+ksonnet applications are initialized based on your current cluster configurations,
+as defined in your` + " `$KUBECONFIG` " + `environment variable. The *Examples*
+section below demonstrates how to customize your configurations.
+
+Creating a ksonnet application results in the following directory tree.
+
+    app-name/
+      .ksonnet/      Metadata for ksonnet
+      app.yaml       Application specifications, ex: name, api version
+      components/    Top-level Kubernetes objects defining the application
+      environments/  Kubernetes cluster definitions
+        default/     Default environment, initialized from the current kubeconfig
+          .metadata/ Contains a versioned ksonnet-lib, see [1] for details
+      lib/           user-written .libsonnet files
+      vendor/        part libraries, prototypes
+
+To begin populating your ksonnet application, see the docs for` + " `ks generate` " + `.
+
+[1] Each environment uses a specific version of ksonnet-lib. Users can set flags
+to generate the library based on a variety of data, including server
+configuration and an OpenAPI specification of a Kubernetes build. By default,
+this is generated from the capabilities of the cluster specified in the cluster
+of the current context specified in` + " `$KUBECONFIG`" + `.
 `,
-	Example: `# Initialize ksonnet application, using the capabilities of live cluster
-# specified in the $KUBECONFIG environment variable (specifically: the
-# current context) to generate 'ksonnet-lib'.
+	Example: `# Initialize a ksonnet application, based on cluster information from the
+# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# More specifically, the current context is used.
 ks init app-name
 
-# Initialize ksonnet application, using the OpenAPI specification generated
-# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
-ks init app-name --api-spec=version:v1.7.1
+# Initialize a ksonnet application, using the context 'dev' from the current
+# kubeconfig file ($KUBECONFIG). This initializes the default environment
+# using the server address and default namespace located at the context 'dev'.
+ks init app-name --context=dev
+
+# Initialize a ksonnet application, using the context 'dev' and the namespace
+# 'dc-west' from the current kubeconfig file ($KUBECONFIG). This initializes
+# the default environment using the server address at the context 'dev' for
+# the namespace 'dc-west'.
+ks init app-name --context=dev --namespace=dc-west
 
-# Initialize ksonnet application, using an OpenAPI specification file
-# generated by a build of Kubernetes to generate 'ksonnet-lib'.
-ks init app-name --api-spec=file:swagger.json
+# Initialize a ksonnet application, using v1.7.1 of the Kubernetes OpenAPI spec
+# to generate 'ksonnet-lib'.
+ks init app-name --api-spec=version:v1.7.1
 
-# Initialize ksonnet application, using the context 'dev' from the kubeconfig
-# file.
-ks init app-name --context=dev`,
+# Initialize a ksonnet application, using the OpenAPI spec generated by a
+# specific build of Kubernetes to generate 'ksonnet-lib'.
+ks init app-name --api-spec=file:swagger.json`,
 }

docs/cli-reference/ks.md

@@ -19,7 +19,7 @@ Synchronise Kubernetes resources with config files
 * [ks diff](ks_diff.md)	 - Display differences between server and local config, or server and server config
 * [ks env](ks_env.md)	 - Manage ksonnet environments
 * [ks generate](ks_generate.md)	 - Expand prototype, place in components/ directory of ksonnet app
-* [ks init](ks_init.md)	 - Initialize a ksonnet project
+* [ks init](ks_init.md)	 - Initialize a ksonnet application
 * [ks param](ks_param.md)	 - Manage ksonnet component parameters
 * [ks pkg](ks_pkg.md)	 - Manage packages and dependencies for the current ksonnet project
 * [ks prototype](ks_prototype.md)	 - Instantiate, inspect, and get examples for ksonnet prototypes

docs/cli-reference/ks_init.md

 ## ks init
 
-Initialize a ksonnet project
+Initialize a ksonnet application
 
 ### Synopsis
 
 
-Initialize a ksonnet project in a new directory, `app-name`. This process
-consists of two steps:
+Initialize a ksonnet application in a new directory, `app-name`.
 
-1. Generating ksonnet-lib. Users can set flags to generate the library based on
-   a variety of data, including server configuration and an OpenAPI
-   specification of a Kubernetes build. By default, this is generated from the
-   capabilities of the cluster specified in the cluster of the current context
-   specified in `$KUBECONFIG`.
-2. Generating the following tree in the current directory.
+This command generates all the project scaffolding required to begin creating and
+deploying components to Kubernetes clusters.
 
-        app-name/
-          .gitignore     Default .gitignore; can customize VCS
-          .ksonnet/      Metadata for ksonnet
-          environments/
-            default/      [Default generated environment]
-          components/    Top-level Kubernetes objects defining application
-          lib/           user-written .libsonnet files
-          vendor/        part libraries, prototypes
+ksonnet applications are initialized based on your current cluster configurations,
+as defined in your `$KUBECONFIG` environment variable. The *Examples*
+section below demonstrates how to customize your configurations.
+
+Creating a ksonnet application results in the following directory tree.
+
+    app-name/
+      .ksonnet/      Metadata for ksonnet
+      app.yaml       Application specifications, ex: name, api version
+      components/    Top-level Kubernetes objects defining the application
+      environments/  Kubernetes cluster definitions
+        default/     Default environment, initialized from the current kubeconfig
+          .metadata/ Contains a versioned ksonnet-lib, see [1] for details
+      lib/           user-written .libsonnet files
+      vendor/        part libraries, prototypes
+
+To begin populating your ksonnet application, see the docs for `ks generate` .
+
+[1] Each environment uses a specific version of ksonnet-lib. Users can set flags
+to generate the library based on a variety of data, including server
+configuration and an OpenAPI specification of a Kubernetes build. By default,
+this is generated from the capabilities of the cluster specified in the cluster
+of the current context specified in `$KUBECONFIG`.
 
 
 ```
@@ -32,22 +42,29 @@ ks init <app-name>
 ### Examples
 
 ```
-# Initialize ksonnet application, using the capabilities of live cluster
-# specified in the $KUBECONFIG environment variable (specifically: the
-# current context) to generate 'ksonnet-lib'.
+# Initialize a ksonnet application, based on cluster information from the
+# active kubeconfig file (specified by the environment variable $KUBECONFIG).
+# More specifically, the current context is used.
 ks init app-name
 
-# Initialize ksonnet application, using the OpenAPI specification generated
-# in the Kubenetes v1.7.1 build to generate 'ksonnet-lib'.
+# Initialize a ksonnet application, using the context 'dev' from the current
+# kubeconfig file ($KUBECONFIG). This initializes the default environment
+# using the server address and default namespace located at the context 'dev'.
+ks init app-name --context=dev
+
+# Initialize a ksonnet application, using the context 'dev' and the namespace
+# 'dc-west' from the current kubeconfig file ($KUBECONFIG). This initializes
+# the default environment using the server address at the context 'dev' for
+# the namespace 'dc-west'.
+ks init app-name --context=dev --namespace=dc-west
+
+# Initialize a ksonnet application, using v1.7.1 of the Kubernetes OpenAPI spec
+# to generate 'ksonnet-lib'.
 ks init app-name --api-spec=version:v1.7.1
 
-# Initialize ksonnet application, using an OpenAPI specification file
-# generated by a build of Kubernetes to generate 'ksonnet-lib'.
+# Initialize a ksonnet application, using the OpenAPI spec generated by a
+# specific build of Kubernetes to generate 'ksonnet-lib'.
 ks init app-name --api-spec=file:swagger.json
-
-# Initialize ksonnet application, using the context 'dev' from the kubeconfig
-# file.
-ks init app-name --context=dev
 ```
 
 ### Options