From a07a0f7c9872f451d4c6c33078597605605e2f88 Mon Sep 17 00:00:00 2001
From: Matt Butcher <mbutcher@engineyard.com>
Date: Thu, 24 Mar 2016 17:43:37 -0600
Subject: [PATCH] doc(cli): improve help output

---
 cmd/helm/chart.go      | 13 +++++++++++--
 cmd/helm/deployment.go | 18 +++++++++++++++---
 cmd/helm/helm.go       | 24 +++++++++++++++++++++++-
 cmd/helm/repository.go | 18 +++++++++++++++---
 cmd/helm/server.go     | 12 ++++++++++++
 5 files changed, 76 insertions(+), 9 deletions(-)

diff --git a/cmd/helm/chart.go b/cmd/helm/chart.go
index e1c7fe52b..bde9b16a9 100644
--- a/cmd/helm/chart.go
+++ b/cmd/helm/chart.go
@@ -31,11 +31,20 @@ func init() {
 	addCommands(chartCommands())
 }
 
+const chartDesc = `A Chart is a package that can be installed and managed by Helm.
+
+   The 'helm chart' subcommands provide tools for working with Helm charts. To
+   get started creating your own chart, use 'helm chart create NAME'.
+
+   For details, use 'helm chart CMD -h'.
+`
+
 func chartCommands() cli.Command {
 	return cli.Command{
 		// Names following form prescribed here: http://is.gd/QUSEOF
-		Name:  "chart",
-		Usage: "Perform chart-centered operations.",
+		Name:        "chart",
+		Usage:       "Perform chart-centered operations.",
+		Description: chartDesc,
 		Subcommands: []cli.Command{
 			{
 				Name:      "config",
diff --git a/cmd/helm/deployment.go b/cmd/helm/deployment.go
index a2975bb18..88655e319 100644
--- a/cmd/helm/deployment.go
+++ b/cmd/helm/deployment.go
@@ -28,6 +28,17 @@ import (
 
 var errMissingDeploymentArg = errors.New("First argument, deployment name, is required. Try 'helm get --help'")
 
+const deploymentDesc = `A deployment is an instance of a Chart running in the cluster.
+
+   Deployments have a name, a chart, and possibly a set of properites. The deployment
+   commands provide tools for managing deployments.
+
+   To deploy a new chart, use the top-level 'helm deploy' command. From there,
+   the 'helm deployment' commands may be used to work with the deployed
+   application.
+
+   For more help, use 'helm deployment CMD -h'.`
+
 const defaultShowFormat = `Name: {{.Name}}
 Status: {{.State.Status}}
 {{with .State.Errors}}Errors:
@@ -41,9 +52,10 @@ func init() {
 func deploymentCommands() cli.Command {
 	return cli.Command{
 		// Names following form prescribed here: http://is.gd/QUSEOF
-		Name:    "deployment",
-		Aliases: []string{"dep"},
-		Usage:   "Perform deployment-centered operations.",
+		Name:        "deployment",
+		Aliases:     []string{"dep"},
+		Usage:       "Perform deployment-centered operations.",
+		Description: deploymentDesc,
 		Subcommands: []cli.Command{
 			{
 				Name:      "config",
diff --git a/cmd/helm/helm.go b/cmd/helm/helm.go
index d1e44923a..ece993dc3 100644
--- a/cmd/helm/helm.go
+++ b/cmd/helm/helm.go
@@ -25,6 +25,28 @@ import (
 	"github.com/kubernetes/helm/pkg/version"
 )
 
+const desc = `Helm: the package and deployment manager for Kubernetes
+
+   Helm is a tool for packaging, deploying, and managing Kubernetes
+   applications. It has a client component (this tool) and several in-cluster
+   components.
+
+   Before you can use Helm to manage applications, you must install the
+   in-cluster components into the target Kubernetes cluster:
+
+      $ helm server install
+
+   Once the in-cluster portion is running, you can use 'helm deploy' to
+   deploy a new application:
+
+      $ helm deploy CHARTNAME
+
+   For more information on Helm commands, you can use the following tools:
+
+      $ helm help          # top-level help
+      $ helm CMD --help    # help for a particular command or set of commands
+`
+
 var commands []cli.Command
 
 func init() {
@@ -41,7 +63,7 @@ func main() {
 	app := cli.NewApp()
 	app.Name = "helm"
 	app.Version = version.Version
-	app.Usage = `Deploy and manage packages.`
+	app.Usage = desc
 	app.Commands = commands
 
 	// TODO: make better
diff --git a/cmd/helm/repository.go b/cmd/helm/repository.go
index 3ec8b1b15..9ff75eb07 100644
--- a/cmd/helm/repository.go
+++ b/cmd/helm/repository.go
@@ -32,11 +32,23 @@ func init() {
 
 const chartRepoPath = "repositories"
 
+const repoDesc = `Helm repositories store Helm charts.
+
+   The repository commands are used to manage which Helm repositories Helm may
+   use as a source for Charts. The repositories are accessed by in-cluster Helm
+   components.
+
+   To list the repositories that your server knows about, use 'helm repo list'.
+
+   For more details, use 'helm repo CMD -h'.
+`
+
 func repoCommands() cli.Command {
 	return cli.Command{
-		Name:    "repository",
-		Aliases: []string{"repo"},
-		Usage:   "Perform chart repository operations.",
+		Name:        "repository",
+		Aliases:     []string{"repo"},
+		Usage:       "Perform chart repository operations.",
+		Description: repoDesc,
 		Subcommands: []cli.Command{
 			{
 				Name:      "add",
diff --git a/cmd/helm/server.go b/cmd/helm/server.go
index 21e948d92..f33649c71 100644
--- a/cmd/helm/server.go
+++ b/cmd/helm/server.go
@@ -37,6 +37,18 @@ func dmCmd() cli.Command {
 	return cli.Command{
 		Name:  "server",
 		Usage: "Manage Helm server-side components",
+		Description: `Server commands manage the in-cluster portion of Helm.
+
+   Helm  has several components that run inside of Kubernetes. Before Helm can
+   be used to install and manage packages, it must be installed into the
+   Kubernetes cluster in which packages will be installed.
+
+   The 'helm server' commands rely upon a properly configured 'kubectl' to
+   communicate with the Kubernetes cluster. To verify that your 'kubectl'
+   client is pointed to the correct cluster, use 'kubectl cluster-info'.
+
+   Use 'helm server install' to install the in-cluster portion of Helm.
+`,
 		Subcommands: []cli.Command{
 			{
 				Name:      "install",