From ba438efe8db89639ae7a8db48743a7609a4628d3 Mon Sep 17 00:00:00 2001
From: Jessica Yao <jessica@heptio.com>
Date: Wed, 29 Nov 2017 20:14:19 -0800
Subject: [PATCH] clean up env reference

Signed-off-by: Jessica Yao <jessica@heptio.com>
---
 cmd/env.go                             | 231 +++++++++++++++----------
 cmd/prototype.go                       |  32 ++--
 docs/cli-reference/ks_env.md           |  78 +++++----
 docs/cli-reference/ks_env_add.md       |  79 ++++-----
 docs/cli-reference/ks_env_list.md      |  16 +-
 docs/cli-reference/ks_env_rm.md        |  24 ++-
 docs/cli-reference/ks_env_set.md       |  35 ++--
 docs/cli-reference/ks_generate.md      |   2 +-
 docs/cli-reference/ks_prototype.md     |   2 +
 docs/cli-reference/ks_prototype_use.md |   2 +-
 10 files changed, 292 insertions(+), 209 deletions(-)

diff --git a/cmd/env.go b/cmd/env.go
index 98dab6b6..566b7367 100644
--- a/cmd/env.go
+++ b/cmd/env.go
@@ -34,6 +34,13 @@ const (
 	flagEnvContext   = "context"
 )
 
+var envShortDesc = map[string]string{
+	"add":  `Add a new environment to a ksonnet application`,
+	"list": `List all environments in a ksonnet application`,
+	"rm":   `Delete an environment from a ksonnet application`,
+	"set":  `Set environment-specific fields (name, namespace, server)`,
+}
+
 func init() {
 	RootCmd.AddCommand(envCmd)
 	bindClientGoFlags(envCmd)
@@ -48,46 +55,48 @@ func init() {
 		"Manually specify API version from OpenAPI schema, cluster, or Kubernetes version")
 
 	envSetCmd.PersistentFlags().String(flagEnvName, "",
-		"Specify name to rename environment to. Name must not already exist")
+		"Name used to uniquely identify the environment. Must not already exist within the ksonnet app")
 }
 
 var envCmd = &cobra.Command{
 	Use:   "env",
 	Short: `Manage ksonnet environments`,
-	Long: `An environment acts as a sort of "named cluster", allowing for commands like
-` + " `ks apply dev` " + `, which applies the ksonnet application to the 'dev cluster'.
-Additionally, environments allow users to cache data about the cluster it points
-to, including data needed to run 'verify', and a version of ksonnet-lib that is
-generated based on the flags the API server was started with (e.g., RBAC enabled
-or not).
-
-An environment contains no user-specific data (such as the private key
-often contained in a kubeconfig file), and
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application. For example, in the example below, there are two
-environments: 'default' and 'us-west/staging'. Each contains a cached version of
-` + " `ksonnet-lib` " + `, and a` + " `spec.json` " + `that contains the server and server cert that
-uniquely identifies the cluster.
-
-    environments/
-      default/           [Default generated environment]
-        .metadata/
-          k.libsonnet
-          k8s.libsonnet
-          swagger.json
-        spec.json
-		default.jsonnet
-        params.libsonnet		
-      us-west/
-        staging/         [Example of user-generated env]
-          .metadata/
-            k.libsonnet
-            k8s.libsonnet
-            swagger.json
-          spec.json      [This will contain the API server address of the environment and other environment metadata]
-		  staging.jsonnet
-          params.libsonnet`,
+	Long: `
+An environment is a deployment target for your ksonnet app and its constituent
+components. You can use ksonnet to deploy a given app to *multiple* environments,
+such as ` + "`dev`" + ` and ` + "`prod`" + `.
+
+Intuitively, an environment acts as a sort of "named cluster", similar to a
+Kubernetes context. (Running ` + "`ks env add --help`" + ` provides more detail
+about the fields that you need to create an environment).
+
+**All of this environment info is cached in local files**. Environments are
+represented as a hierarchy in the ` + "`environments/`" + ` directory of a ksonnet app, like
+'default' and 'us-west/staging' in the example below.
+
+` + "```" + `
+├── environments
+│   ├── base.libsonnet
+│   ├── default                      // Default generated environment ('ks init')
+│   │   ├── .metadata
+│   │   │   ├── k.libsonnet
+│   │   │   ├── k8s.libsonnet
+│   │   │   └── swagger.json
+│   │   ├── main.jsonnet
+│   │   ├── params.libsonnet
+│   │   └── spec.json
+│   └── us-west
+│       └── staging                  // Example of user-generated env ('ks env add')
+│           ├── .metadata
+│           │   ├── k.libsonnet      // Jsonnet library with Kubernetes-compatible types and definitions
+│           │   ├── k8s.libsonnet
+│           │   └── swagger.json
+│           ├── main.libsonnet
+│           ├── params.libsonnet     // Can be used to customize components *per-environment*
+│           └── spec.json            // This will contain the environment's API server address and namespace
+` + "```" + `
+----
+`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 0 {
 			return fmt.Errorf("%s is not a valid subcommand\n\n%s", strings.Join(args, " "), cmd.UsageString())
@@ -98,7 +107,7 @@ uniquely identifies the cluster.
 
 var envAddCmd = &cobra.Command{
 	Use:   "add <env-name>",
-	Short: "Add a new environment to a ksonnet project",
+	Short: envShortDesc["add"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		flags := cmd.Flags()
 		if len(args) != 1 {
@@ -136,55 +145,56 @@ var envAddCmd = &cobra.Command{
 		return c.Run()
 	},
 
-	Long: `Add a new environment to a ksonnet project. Names are restricted to not
-include punctuation, so names like` + " `../foo` " + `are not allowed.
-
-An environment acts as a sort of "named cluster", allowing for commands like
-` + " `ks apply dev` " + `, which applies the ksonnet application to the "dev cluster".
-For more information on what an environment is and how they work, run` + " `ks help env` " + `.
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application, and hence` + " `ks env add` " + `will add to this directory structure.
-For example, in the example below, there are two environments: 'default' and
-'us-west/staging'.` + " `ks env add` " + `will add a similar directory to this environment.
-
-    environments/
-      default/           [Default generated environment]
-        .metadata/
-          k.libsonnet
-          k8s.libsonnet
-          swagger.json
-        spec.json
-		default.jsonnet
-        params.libsonnet
-      us-west/
-        staging/         [Example of user-generated env]
-          .metadata/
-            k.libsonnet
-            k8s.libsonnet
-            swagger.json
-          spec.json      [This will contain the API server address of the environment and other environment metadata],
-		  staging.jsonnet
-          params.libsonnet`,
-	Example: `# Initialize a new staging environment at 'us-west'.
-# The environment will be setup using the current context in your kubecfg file. The directory
-# structure rooted at 'us-west' in the documentation above will be generated.
+	Long: `
+The ` + "`add`" + ` command creates a new environment (specifically for the ksonnet app
+whose directory it's executed in). This environment is cached with the following
+info:
+
+1. **Name** — A string used to uniquely identify the environment.
+2. **Server** — The address and port of a Kubernetes API server (i.e. cluster).
+3. **Namespace**  — A Kubernetes namespace. *Must already exist on the cluster.*
+4. **Kubernetes API Version**  — Used to generate a library with compatible type defs.
+
+(1) is mandatory. (2) and (3) can be inferred from $KUBECONFIG, *or* from the
+` + "`--kubeconfig`" + ` or ` + "`--context`" + ` flags. Otherwise, (2), (3), and (4) can all be
+specified by individual flags.
+
+Note that an environment *DOES NOT* contain user-specific data such as private keys.
+
+### Related Commands
+
+* ` + "`ks env list` " + `— ` + protoShortDesc["list"] + `
+* ` + "`ks param set` " + `— ` + `Change the values of an existing component` + `
+* ` + "`ks apply` " + `— ` + `Apply your component manifests to a cluster` + `
+
+### Syntax
+`,
+	Example: `
+# Initialize a new environment, called "staging". No flags are set, so 'server'
+# and 'namespace' info are pulled from the file specified by $KUBECONFIG.
+# 'version' defaults to "version:1.7.0".
 ks env add us-west/staging
 
-# Initialize a new staging environment at 'us-west' with the namespace 'staging', using
-# the OpenAPI specification generated in the Kubernetes v1.7.1 build to generate 'ksonnet-lib'.
+# Initialize a new environment called "us-west/staging" with the pre-existing
+# namespace 'staging'. 'version' is specified, so the OpenAPI spec from the
+# Kubernetes v1.7.1 build is used to generate the helper library 'ksonnet-lib'.
+#
+# NOTE: "us-west/staging" indicates a hierarchical structure, so the env-specific
+# files here are saved in "<ksonnet-app-root>/environments/us-west/staging".
 ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=staging
 
-# Initialize a new environment using the 'dev' context in your kubeconfig file.
+# Initialize a new environment "my-env" using the "dev" context in your current
+# kubeconfig file ($KUBECONFIG).
 ks env add my-env --context=dev
 
-# Initialize a new environment using a server address.
-ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com`,
+# Initialize a new environment "prod" using the address of a cluster's Kubernetes
+# API server.
+ks env add prod --server=https://ksonnet-1.us-west.elb.amazonaws.com`,
 }
 
 var envRmCmd = &cobra.Command{
 	Use:   "rm <env-name>",
-	Short: "Delete an environment from a ksonnet project",
+	Short: envShortDesc["rm"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
 			return fmt.Errorf("'env rm' takes a single argument, that is the name of the environment")
@@ -210,17 +220,29 @@ var envRmCmd = &cobra.Command{
 
 		return c.Run()
 	},
-	Long: `Delete an environment from a ksonnet project. This is the same
-as removing the <env-name> environment directory and all files contained. All empty
-parent directories are also subsequently deleted.`,
-	Example: `# Remove the directory 'us-west/staging' and all contents in the 'environments'
-# directory. This will also remove the parent directory 'us-west' if it is empty.
+	Long: `
+The ` + "`rm`" + ` command deletes an environment from a ksonnet application. This is
+the same as removing the ` + "`<env-name>`" + ` environment directory and all files
+contained. All empty parent directories are also subsequently deleted.
+
+NOTE: This does *NOT* delete the components running in ` + "`<env-name>`" + `. To do that, you
+need to use the ` + "`ks delete`" + ` command.
+
+### Related Commands
+
+* ` + "`ks delete` " + `— ` + `Delete all the app components running in an environment (cluster)` + `
+
+### Syntax
+`,
+	Example: `
+# Remove the directory 'environments/us-west/staging' and all of its contents.
+# This will also remove the parent directory 'us-west' if it is empty.
 ks env rm us-west/staging`,
 }
 
 var envListCmd = &cobra.Command{
 	Use:   "list",
-	Short: "List all environments in a ksonnet project",
+	Short: envShortDesc["list"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 0 {
 			return fmt.Errorf("'env list' takes zero arguments")
@@ -243,13 +265,23 @@ var envListCmd = &cobra.Command{
 		}
 
 		return c.Run(cmd.OutOrStdout())
-	}, Long: `List all environments in a ksonnet project. This will
-display the name, server, and namespace of each environment within the ksonnet project.`,
+	}, Long: `
+The ` + "`list`" + ` command lists all of the available environments for the
+current ksonnet app. Specifically, this will display the (1) *name*,
+(2) *server*, and (3) *namespace* of each environment.
+
+### Related Commands
+
+* ` + "`ks env set` " + `— ` + envShortDesc["set"] + `
+* ` + "`ks env rm` " + `— ` + envShortDesc["rm"] + `
+
+### Syntax
+`,
 }
 
 var envSetCmd = &cobra.Command{
 	Use:   "set <env-name>",
-	Short: "Set environment fields such as the name, server, and namespace.",
+	Short: envShortDesc["set"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		flags := cmd.Flags()
 		if len(args) != 1 {
@@ -283,21 +315,32 @@ var envSetCmd = &cobra.Command{
 
 		return c.Run()
 	},
-	Long: `Set environment fields such as the name, and server. Changing
-the name of an environment will also update the directory structure in
-'environments'.`,
-	Example: `# Updates the API server address of the environment 'us-west/staging'.
+	Long: `
+The ` + "`set`" + ` command lets you change the fields of an existing environment.
+You can update any of your environment's (1) name (2) namespace and
+(3) server (cluster URI).
+
+Note that changing the name of an environment will also update the corresponding
+directory structure in ` + "`environments/`" + `.
+
+### Related Commands
+
+* ` + "`ks env list` " + `— ` + envShortDesc["list"] + `
+
+### Syntax
+`,
+	Example: `# Update the API server address of the environment 'us-west/staging'.
 ks env set us-west/staging --server=http://example.com
 
-# Updates the namespace of the environment 'us-west/staging'.
+# Update the namespace of the environment 'us-west/staging'.
 ks env set us-west/staging --namespace=staging
 
-# Updates both the name and the server of the environment 'us-west/staging'.
-# Updating the name will update the directory structure in 'environments'.
+# Update both the name and the server of the environment 'us-west/staging'.
+# Updating the name will update the directory structure in 'environments/'.
 ks env set us-west/staging --server=http://example.com --name=us-east/staging
-  
-# Updates API server address of the environment 'us-west/staging' based on the
-# server in the context 'staging-west' in your kubeconfig file.
+
+# Update the API server address of the environment 'us-west/staging' based on the
+# server in the 'staging-west' context of your kubeconfig file.
 ks env set us-west/staging --context=staging-west`,
 }
 
diff --git a/cmd/prototype.go b/cmd/prototype.go
index 9ab227ef..169218cf 100644
--- a/cmd/prototype.go
+++ b/cmd/prototype.go
@@ -40,7 +40,7 @@ func init() {
 	prototypeCmd.AddCommand(prototypePreviewCmd)
 }
 
-var cmdShortDesc = map[string]string{
+var protoShortDesc = map[string]string{
 	"list":     `List all locally available ksonnet prototypes`,
 	"describe": `See more info about a prototype's output and usage`,
 	"preview":  `Preview a prototype's output without creating a component (stdout)`,
@@ -70,12 +70,14 @@ These complete manifests are output into your ` + "`components/`" + ` directory.
 words, prototypes provide the basis for the **components** of your app. You can
 use prototypes to autogenerate boilerplate code and focus on customizing them
 for your use case.
+
+----
 `,
 }
 
 var prototypeListCmd = &cobra.Command{
 	Use:   "list",
-	Short: cmdShortDesc["list"],
+	Short: protoShortDesc["list"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 0 {
 			return fmt.Errorf("Command 'prototype list' does not take any arguments")
@@ -120,9 +122,9 @@ from the *incubator* registry.
 
 ### Related Commands
 
-* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
-* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
-* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks prototype preview` " + `— ` + protoShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + protoShortDesc["use"] + `
 * ` + "`ks pkg install` " + `— Install more prototypes (from external packages)
 
 ### Syntax
@@ -131,7 +133,7 @@ from the *incubator* registry.
 
 var prototypeDescribeCmd = &cobra.Command{
 	Use:   "describe <prototype-name>",
-	Short: cmdShortDesc["describe"],
+	Short: protoShortDesc["describe"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
 			return fmt.Errorf("Command 'prototype describe' requires a prototype name\n\n%s", cmd.UsageString())
@@ -187,8 +189,8 @@ the specified prototype (identified by name). Specifically, this describes:
 
 ### Related Commands
 
-* ` + "`ks prototype preview` " + `— ` + cmdShortDesc["preview"] + `
-* ` + "`ks prototype use` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks prototype preview` " + `— ` + protoShortDesc["preview"] + `
+* ` + "`ks prototype use` " + `— ` + protoShortDesc["use"] + `
 
 ### Syntax
 `,
@@ -200,7 +202,7 @@ ks prototype describe deployment`,
 
 var prototypeSearchCmd = &cobra.Command{
 	Use:   "search <name-substring>",
-	Short: cmdShortDesc["search"],
+	Short: protoShortDesc["search"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
 			return fmt.Errorf("Command 'prototype search' requires a prototype name\n\n%s", cmd.UsageString())
@@ -226,8 +228,8 @@ Specifically, it matches any prototypes with names that contain the string <name
 
 ### Related Commands
 
-* ` + "`ks prototype describe` " + `— ` + cmdShortDesc["describe"] + `
-* ` + "`ks prototype list` " + `— ` + cmdShortDesc["list"] + `
+* ` + "`ks prototype describe` " + `— ` + protoShortDesc["describe"] + `
+* ` + "`ks prototype list` " + `— ` + protoShortDesc["list"] + `
 
 ### Syntax
 `,
@@ -238,7 +240,7 @@ ks prototype search service`,
 
 var prototypePreviewCmd = &cobra.Command{
 	Use:                "preview <prototype-name> [parameter-flags]",
-	Short:              cmdShortDesc["preview"],
+	Short:              protoShortDesc["preview"],
 	DisableFlagParsing: true,
 	RunE: func(cmd *cobra.Command, rawArgs []string) error {
 		if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
@@ -318,7 +320,7 @@ a component with ` + "`ks generate`" + ` and then use ` + "`ks show`" + `.
 
 ### Related Commands
 
-* ` + "`ks generate` " + `— ` + cmdShortDesc["use"] + `
+* ` + "`ks generate` " + `— ` + protoShortDesc["use"] + `
 
 ### Syntax
 `,
@@ -342,7 +344,7 @@ var generateCmd = &cobra.Command{
 
 var prototypeUseCmd = &cobra.Command{
 	Use:                "use <prototype-name> <componentName> [type] [parameter-flags]",
-	Short:              cmdShortDesc["use"],
+	Short:              protoShortDesc["use"],
 	DisableFlagParsing: true,
 	RunE: func(cmd *cobra.Command, rawArgs []string) error {
 		if len(rawArgs) == 1 && (rawArgs[0] == "--help" || rawArgs[0] == "-h") {
@@ -453,7 +455,7 @@ different prototypes support their own unique flags.
 ### Related Commands
 
 * ` + "`ks apply` " + `— Apply your component manifests to a cluster
-* ` + "`ks param set` " + `— Change the values you specified when generating the component
+* ` + "`ks param set` " + `— Change the values of an existing component
 
 ### Syntax
 `,
diff --git a/docs/cli-reference/ks_env.md b/docs/cli-reference/ks_env.md
index 6d397b57..69b152cf 100644
--- a/docs/cli-reference/ks_env.md
+++ b/docs/cli-reference/ks_env.md
@@ -5,40 +5,42 @@ Manage ksonnet environments
 ### Synopsis
 
 
-An environment acts as a sort of "named cluster", allowing for commands like
- `ks apply dev` , which applies the ksonnet application to the 'dev cluster'.
-Additionally, environments allow users to cache data about the cluster it points
-to, including data needed to run 'verify', and a version of ksonnet-lib that is
-generated based on the flags the API server was started with (e.g., RBAC enabled
-or not).
-
-An environment contains no user-specific data (such as the private key
-often contained in a kubeconfig file), and
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application. For example, in the example below, there are two
-environments: 'default' and 'us-west/staging'. Each contains a cached version of
- `ksonnet-lib` , and a `spec.json` that contains the server and server cert that
-uniquely identifies the cluster.
-
-    environments/
-      default/           [Default generated environment]
-        .metadata/
-          k.libsonnet
-          k8s.libsonnet
-          swagger.json
-        spec.json
-		default.jsonnet
-        params.libsonnet		
-      us-west/
-        staging/         [Example of user-generated env]
-          .metadata/
-            k.libsonnet
-            k8s.libsonnet
-            swagger.json
-          spec.json      [This will contain the API server address of the environment and other environment metadata]
-		  staging.jsonnet
-          params.libsonnet
+
+An environment is a deployment target for your ksonnet app and its constituent
+components. You can use ksonnet to deploy a given app to *multiple* environments,
+such as `dev` and `prod`.
+
+Intuitively, an environment acts as a sort of "named cluster", similar to a
+Kubernetes context. (Running `ks env add --help` provides more detail
+about the fields that you need to create an environment).
+
+**All of this environment info is cached in local files**. Environments are
+represented as a hierarchy in the `environments/` directory of a ksonnet app, like
+'default' and 'us-west/staging' in the example below.
+
+```
+├── environments
+│   ├── base.libsonnet
+│   ├── default                      // Default generated environment ('ks init')
+│   │   ├── .metadata
+│   │   │   ├── k.libsonnet
+│   │   │   ├── k8s.libsonnet
+│   │   │   └── swagger.json
+│   │   ├── main.jsonnet
+│   │   ├── params.libsonnet
+│   │   └── spec.json
+│   └── us-west
+│       └── staging                  // Example of user-generated env ('ks env add')
+│           ├── .metadata
+│           │   ├── k.libsonnet      // Jsonnet library with Kubernetes-compatible types and definitions
+│           │   ├── k8s.libsonnet
+│           │   └── swagger.json
+│           ├── main.libsonnet
+│           ├── params.libsonnet     // Can be used to customize components *per-environment*
+│           └── spec.json            // This will contain the environment's API server address and namespace
+```
+----
+
 
 ```
 ks env
@@ -72,8 +74,8 @@ ks env
 
 ### SEE ALSO
 * [ks](ks.md)	 - Synchronise Kubernetes resources with config files
-* [ks env add](ks_env_add.md)	 - Add a new environment to a ksonnet project
-* [ks env list](ks_env_list.md)	 - List all environments in a ksonnet project
-* [ks env rm](ks_env_rm.md)	 - Delete an environment from a ksonnet project
-* [ks env set](ks_env_set.md)	 - Set environment fields such as the name, server, and namespace.
+* [ks env add](ks_env_add.md)	 - Add a new environment to a ksonnet application
+* [ks env list](ks_env_list.md)	 - List all environments in a ksonnet application
+* [ks env rm](ks_env_rm.md)	 - Delete an environment from a ksonnet application
+* [ks env set](ks_env_set.md)	 - Set environment-specific fields (name, namespace, server)
 
diff --git a/docs/cli-reference/ks_env_add.md b/docs/cli-reference/ks_env_add.md
index 5608089d..2bb38657 100644
--- a/docs/cli-reference/ks_env_add.md
+++ b/docs/cli-reference/ks_env_add.md
@@ -1,40 +1,34 @@
 ## ks env add
 
-Add a new environment to a ksonnet project
+Add a new environment to a ksonnet application
 
 ### Synopsis
 
 
-Add a new environment to a ksonnet project. Names are restricted to not
-include punctuation, so names like `../foo` are not allowed.
-
-An environment acts as a sort of "named cluster", allowing for commands like
- `ks apply dev` , which applies the ksonnet application to the "dev cluster".
-For more information on what an environment is and how they work, run `ks help env` .
-
-Environments are represented as a hierarchy in the 'environments' directory of a
-ksonnet application, and hence `ks env add` will add to this directory structure.
-For example, in the example below, there are two environments: 'default' and
-'us-west/staging'. `ks env add` will add a similar directory to this environment.
-
-    environments/
-      default/           [Default generated environment]
-        .metadata/
-          k.libsonnet
-          k8s.libsonnet
-          swagger.json
-        spec.json
-		default.jsonnet
-        params.libsonnet
-      us-west/
-        staging/         [Example of user-generated env]
-          .metadata/
-            k.libsonnet
-            k8s.libsonnet
-            swagger.json
-          spec.json      [This will contain the API server address of the environment and other environment metadata],
-		  staging.jsonnet
-          params.libsonnet
+
+The `add` command creates a new environment (specifically for the ksonnet app
+whose directory it's executed in). This environment is cached with the following
+info:
+
+1. **Name** — A string used to uniquely identify the environment.
+2. **Server** — The address and port of a Kubernetes API server (i.e. cluster).
+3. **Namespace**  — A Kubernetes namespace. *Must already exist on the cluster.*
+4. **Kubernetes API Version**  — Used to generate a library with compatible type defs.
+
+(1) is mandatory. (2) and (3) can be inferred from $KUBECONFIG, *or* from the
+`--kubeconfig` or `--context` flags. Otherwise, (2), (3), and (4) can all be
+specified by individual flags.
+
+Note that an environment *DOES NOT* contain user-specific data such as private keys.
+
+### Related Commands
+
+* `ks env list` — List all locally available ksonnet prototypes
+* `ks param set` — Change the values of an existing component
+* `ks apply` — Apply your component manifests to a cluster
+
+### Syntax
+
 
 ```
 ks env add <env-name>
@@ -43,20 +37,27 @@ ks env add <env-name>
 ### Examples
 
 ```
-# Initialize a new staging environment at 'us-west'.
-# The environment will be setup using the current context in your kubecfg file. The directory
-# structure rooted at 'us-west' in the documentation above will be generated.
+
+# Initialize a new environment, called "staging". No flags are set, so 'server'
+# and 'namespace' info are pulled from the file specified by $KUBECONFIG.
+# 'version' defaults to "version:1.7.0".
 ks env add us-west/staging
 
-# Initialize a new staging environment at 'us-west' with the namespace 'staging', using
-# the OpenAPI specification generated in the Kubernetes v1.7.1 build to generate 'ksonnet-lib'.
+# Initialize a new environment called "us-west/staging" with the pre-existing
+# namespace 'staging'. 'version' is specified, so the OpenAPI spec from the
+# Kubernetes v1.7.1 build is used to generate the helper library 'ksonnet-lib'.
+#
+# NOTE: "us-west/staging" indicates a hierarchical structure, so the env-specific
+# files here are saved in "<ksonnet-app-root>/environments/us-west/staging".
 ks env add us-west/staging --api-spec=version:v1.7.1 --namespace=staging
 
-# Initialize a new environment using the 'dev' context in your kubeconfig file.
+# Initialize a new environment "my-env" using the "dev" context in your current
+# kubeconfig file ($KUBECONFIG).
 ks env add my-env --context=dev
 
-# Initialize a new environment using a server address.
-ks env add my-env --server=https://ksonnet-1.us-west.elb.amazonaws.com
+# Initialize a new environment "prod" using the address of a cluster's Kubernetes
+# API server.
+ks env add prod --server=https://ksonnet-1.us-west.elb.amazonaws.com
 ```
 
 ### Options
diff --git a/docs/cli-reference/ks_env_list.md b/docs/cli-reference/ks_env_list.md
index 694c22b9..52ac3eae 100644
--- a/docs/cli-reference/ks_env_list.md
+++ b/docs/cli-reference/ks_env_list.md
@@ -1,12 +1,22 @@
 ## ks env list
 
-List all environments in a ksonnet project
+List all environments in a ksonnet application
 
 ### Synopsis
 
 
-List all environments in a ksonnet project. This will
-display the name, server, and namespace of each environment within the ksonnet project.
+
+The `list` command lists all of the available environments for the
+current ksonnet app. Specifically, this will display the (1) *name*,
+(2) *server*, and (3) *namespace* of each environment.
+
+### Related Commands
+
+* `ks env set` — Set environment-specific fields (name, namespace, server)
+* `ks env rm` — Delete an environment from a ksonnet application
+
+### Syntax
+
 
 ```
 ks env list
diff --git a/docs/cli-reference/ks_env_rm.md b/docs/cli-reference/ks_env_rm.md
index 654a8858..1b28fc38 100644
--- a/docs/cli-reference/ks_env_rm.md
+++ b/docs/cli-reference/ks_env_rm.md
@@ -1,13 +1,24 @@
 ## ks env rm
 
-Delete an environment from a ksonnet project
+Delete an environment from a ksonnet application
 
 ### Synopsis
 
 
-Delete an environment from a ksonnet project. This is the same
-as removing the <env-name> environment directory and all files contained. All empty
-parent directories are also subsequently deleted.
+
+The `rm` command deletes an environment from a ksonnet application. This is
+the same as removing the `<env-name>` environment directory and all files
+contained. All empty parent directories are also subsequently deleted.
+
+NOTE: This does *NOT* delete the components running in `<env-name>`. To do that, you
+need to use the `ks delete` command.
+
+### Related Commands
+
+* `ks delete` — Delete all the app components running in an environment (cluster)
+
+### Syntax
+
 
 ```
 ks env rm <env-name>
@@ -16,8 +27,9 @@ ks env rm <env-name>
 ### Examples
 
 ```
-# Remove the directory 'us-west/staging' and all contents in the 'environments'
-# directory. This will also remove the parent directory 'us-west' if it is empty.
+
+# Remove the directory 'environments/us-west/staging' and all of its contents.
+# This will also remove the parent directory 'us-west' if it is empty.
 ks env rm us-west/staging
 ```
 
diff --git a/docs/cli-reference/ks_env_set.md b/docs/cli-reference/ks_env_set.md
index 3a4a4ff6..6d36cc04 100644
--- a/docs/cli-reference/ks_env_set.md
+++ b/docs/cli-reference/ks_env_set.md
@@ -1,13 +1,24 @@
 ## ks env set
 
-Set environment fields such as the name, server, and namespace.
+Set environment-specific fields (name, namespace, server)
 
 ### Synopsis
 
 
-Set environment fields such as the name, and server. Changing
-the name of an environment will also update the directory structure in
-'environments'.
+
+The `set` command lets you change the fields of an existing environment.
+You can update any of your environment's (1) name (2) namespace and
+(3) server (cluster URI).
+
+Note that changing the name of an environment will also update the corresponding
+directory structure in `environments/`.
+
+### Related Commands
+
+* `ks env list` — List all environments in a ksonnet application
+
+### Syntax
+
 
 ```
 ks env set <env-name>
@@ -16,25 +27,25 @@ ks env set <env-name>
 ### Examples
 
 ```
-# Updates the API server address of the environment 'us-west/staging'.
+# Update the API server address of the environment 'us-west/staging'.
 ks env set us-west/staging --server=http://example.com
 
-# Updates the namespace of the environment 'us-west/staging'.
+# Update the namespace of the environment 'us-west/staging'.
 ks env set us-west/staging --namespace=staging
 
-# Updates both the name and the server of the environment 'us-west/staging'.
-# Updating the name will update the directory structure in 'environments'.
+# Update both the name and the server of the environment 'us-west/staging'.
+# Updating the name will update the directory structure in 'environments/'.
 ks env set us-west/staging --server=http://example.com --name=us-east/staging
-  
-# Updates API server address of the environment 'us-west/staging' based on the
-# server in the context 'staging-west' in your kubeconfig file.
+
+# Update the API server address of the environment 'us-west/staging' based on the
+# server in the 'staging-west' context of your kubeconfig file.
 ks env set us-west/staging --context=staging-west
 ```
 
 ### Options
 
 ```
-      --name string   Specify name to rename environment to. Name must not already exist
+      --name string   Name used to uniquely identify the environment. Must not already exist within the ksonnet app
 ```
 
 ### Options inherited from parent commands
diff --git a/docs/cli-reference/ks_generate.md b/docs/cli-reference/ks_generate.md
index 993a18d4..681eba5d 100644
--- a/docs/cli-reference/ks_generate.md
+++ b/docs/cli-reference/ks_generate.md
@@ -33,7 +33,7 @@ different prototypes support their own unique flags.
 ### Related Commands
 
 * `ks apply` — Apply your component manifests to a cluster
-* `ks param set` — Change the values you specified when generating the component
+* `ks param set` — Change the values of an existing component
 
 ### Syntax
 
diff --git a/docs/cli-reference/ks_prototype.md b/docs/cli-reference/ks_prototype.md
index d9d53fca..c7f5d941 100644
--- a/docs/cli-reference/ks_prototype.md
+++ b/docs/cli-reference/ks_prototype.md
@@ -19,6 +19,8 @@ words, prototypes provide the basis for the **components** of your app. You can
 use prototypes to autogenerate boilerplate code and focus on customizing them
 for your use case.
 
+----
+
 
 ```
 ks prototype
diff --git a/docs/cli-reference/ks_prototype_use.md b/docs/cli-reference/ks_prototype_use.md
index 49de3946..32365e74 100644
--- a/docs/cli-reference/ks_prototype_use.md
+++ b/docs/cli-reference/ks_prototype_use.md
@@ -33,7 +33,7 @@ different prototypes support their own unique flags.
 ### Related Commands
 
 * `ks apply` — Apply your component manifests to a cluster
-* `ks param set` — Change the values you specified when generating the component
+* `ks param set` — Change the values of an existing component
 
 ### Syntax
 
-- 
GitLab