clean up registry docs

Signed-off-by: Jessica Yao <jessica@heptio.com>

cmd/registry.go

@@ -16,6 +16,11 @@ func init() {
 	registryCmd.AddCommand(registryDescribeCmd)
 }
 
+var regShortDesc = map[string]string{
+	"list":     `List all registries known to the current ksonnet app.`,
+	"describe": `Describe a ksonnet registry and the packages it contains`,
+}
+
 var registryCmd = &cobra.Command{
 	Use:   "registry",
 	Short: `Manage registries for current project`,
@@ -25,24 +30,28 @@ var registryCmd = &cobra.Command{
 		}
 		return fmt.Errorf("Command 'registry' requires a subcommand\n\n%s", cmd.UsageString())
 	},
-	Long: `Manage and inspect ksonnet registries.
-
-Registries contain a set of versioned libraries that the user can install and
-manage in a ksonnet project using the CLI. A typical library contains:
-
-  1. A set of "parts", pre-fabricated API objects which can be combined together
-     to configure a Kubernetes application for some task. For example, the Redis
-     library may contain a Deployment, a Service, a Secret, and a
-     PersistentVolumeClaim, but if the user is operating it as a cache, they may
-     only need the first three of these.
-  2. A set of "prototypes", which are pre-fabricated combinations of these
-     parts, made to make it easier to get started using a library. See the
-     documentation for 'ks prototype' for more information.`,
+	Long: `
+A ksonnet registry is basically a repository for *packages*. (Registry here is
+used in the same sense as a container image registry). Registries are identified
+by a ` + "`registry.yaml`" + ` in their root that declares which packages they contain.
+
+Specifically, registries contain a set of versioned packages that the user can
+install and manage in a given ksonnet app, using the CLI. A typical package contains:
+
+1. **A library definining a set of "parts"**. These are pre-fabricated API objects
+which can be combined together to configure a Kubernetes application for some task.
+(e.g. a Deployment, a Service, and a Secret, specifically tailored for Redis).
+
+2. **A set of "prototypes"**, which are pre-fabricated combinations of parts, as
+described above. (See ` + "`ks prototype --help`" + ` for more information.)
+
+----
+`,
 }
 
 var registryListCmd = &cobra.Command{
 	Use:   "list",
-	Short: `List all registries known to the current ksonnet app.`,
+	Short: regShortDesc["list"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		const (
 			nameHeader     = "NAME"
@@ -89,11 +98,25 @@ var registryListCmd = &cobra.Command{
 		fmt.Print(formatted)
 		return nil
 	},
+	Long: `
+The ` + "`list`" + ` command displays all known ksonnet registries in a table. This
+table includes the following info:
+
+1. Registry name
+2. Protocol (e.g. ` + "`github`" + `)
+3. Registry URI
+
+### Related Commands
+
+* ` + "`ks registry describe` " + `— ` + regShortDesc["describe"] + `
+
+### Syntax
+`,
 }
 
 var registryDescribeCmd = &cobra.Command{
 	Use:   "describe <registry-name>",
-	Short: `Describe a ksonnet registry`,
+	Short: regShortDesc["describe"],
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if len(args) != 1 {
 			return fmt.Errorf("Command 'registry describe' takes one argument, which is the name of the registry to describe")
@@ -135,7 +158,7 @@ var registryDescribeCmd = &cobra.Command{
 		fmt.Println(`PROTOCOL:`)
 		fmt.Println(regRef.Protocol)
 		fmt.Println()
-		fmt.Println(`LIBRARIES:`)
+		fmt.Println(`PACKAGES:`)
 
 		for _, lib := range reg.Libraries {
 			fmt.Printf("  %s\n", lib.Path)
@@ -144,6 +167,18 @@ var registryDescribeCmd = &cobra.Command{
 		return nil
 	},
 
-	Long: `Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some` + " `registry-name`" + `.`,
+	Long: `
+The ` + "`describe`" + ` command outputs documentation for the ksonnet registry identified
+by `+ "`<registry-name>`" + `. Specifically, it displays the following:
+
+1. Registry URI
+2. Protocol (e.g. ` + "`github`" + `)
+3. List of packages included in the registry
+
+### Related Commands
+
+* ` + "`ks pkg install` " + `— ` + pkgShortDesc["install"] + `
+
+### Syntax
+`,
 }

docs/cli-reference/ks_registry.md

@@ -5,19 +5,23 @@ Manage registries for current project
 ### Synopsis
 
 
-Manage and inspect ksonnet registries.
 
-Registries contain a set of versioned libraries that the user can install and
-manage in a ksonnet project using the CLI. A typical library contains:
+A ksonnet registry is basically a repository for *packages*. (Registry here is
+used in the same sense as a container image registry). Registries are identified
+by a `registry.yaml` in their root that declares which packages they contain.
+
+Specifically, registries contain a set of versioned packages that the user can
+install and manage in a given ksonnet app, using the CLI. A typical package contains:
+
+1. **A library definining a set of "parts"**. These are pre-fabricated API objects
+which can be combined together to configure a Kubernetes application for some task.
+(e.g. a Deployment, a Service, and a Secret, specifically tailored for Redis).
+
+2. **A set of "prototypes"**, which are pre-fabricated combinations of parts, as
+described above. (See `ks prototype --help` for more information.)
+
+----
 
-  1. A set of "parts", pre-fabricated API objects which can be combined together
-     to configure a Kubernetes application for some task. For example, the Redis
-     library may contain a Deployment, a Service, a Secret, and a
-     PersistentVolumeClaim, but if the user is operating it as a cache, they may
-     only need the first three of these.
-  2. A set of "prototypes", which are pre-fabricated combinations of these
-     parts, made to make it easier to get started using a library. See the
-     documentation for 'ks prototype' for more information.
 
 ```
 ks registry
@@ -31,6 +35,6 @@ ks registry
 
 ### SEE ALSO
 * [ks](ks.md)	 - Configure your application to deploy to a Kubernetes cluster
-* [ks registry describe](ks_registry_describe.md)	 - Describe a ksonnet registry
+* [ks registry describe](ks_registry_describe.md)	 - Describe a ksonnet registry and the packages it contains
 * [ks registry list](ks_registry_list.md)	 - List all registries known to the current ksonnet app.
 

docs/cli-reference/ks_registry_describe.md

 ## ks registry describe
 
-Describe a ksonnet registry
+Describe a ksonnet registry and the packages it contains
 
 ### Synopsis
 
 
-Output documentation for some ksonnet registry prototype uniquely identified in
-the current ksonnet project by some `registry-name`.
+
+The `describe` command outputs documentation for the ksonnet registry identified
+by `<registry-name>`. Specifically, it displays the following:
+
+1. Registry URI
+2. Protocol (e.g. `github`)
+3. List of packages included in the registry
+
+### Related Commands
+
+* `ks pkg install` — Install a package (e.g. extra prototypes) for the current ksonnet app
+
+### Syntax
+
 
 ```
 ks registry describe <registry-name>

docs/cli-reference/ks_registry_list.md

@@ -5,7 +5,20 @@ List all registries known to the current ksonnet app.
 ### Synopsis
 
 
-List all registries known to the current ksonnet app.
+
+The `list` command displays all known ksonnet registries in a table. This
+table includes the following info:
+
+1. Registry name
+2. Protocol (e.g. `github`)
+3. Registry URI
+
+### Related Commands
+
+* `ks registry describe` — Describe a ksonnet registry and the packages it contains
+
+### Syntax
+
 
 ```
 ks registry list