diff --git a/cmd/gendocs/gen_kubectl_docs.go b/cmd/gendocs/gen_kubectl_docs.go
index e8d2ec72183af..a0fee8d2b8f59 100644
--- a/cmd/gendocs/gen_kubectl_docs.go
+++ b/cmd/gendocs/gen_kubectl_docs.go
@@ -65,10 +65,10 @@ func genMarkdown(command *cobra.Command, parent, docsDir string) {
 	fmt.Fprintf(out, "## %s\n\n", name)
 	fmt.Fprintf(out, "%s\n\n", short)
 	fmt.Fprintf(out, "### Synopsis\n\n")
-	fmt.Fprintf(out, "```\n%s\n```\n\n", long)
+	fmt.Fprintf(out, "\n%s\n\n", long)
 
 	if command.Runnable() {
-		fmt.Fprintf(out, "%s\n\n", command.UseLine())
+		fmt.Fprintf(out, "```\n%s\n```\n\n", command.UseLine())
 	}
 
 	if len(command.Example) > 0 {
diff --git a/docs/kubectl-clusterinfo.md b/docs/kubectl-clusterinfo.md
index 3677e6723c11c..8b5bfff601729 100644
--- a/docs/kubectl-clusterinfo.md
+++ b/docs/kubectl-clusterinfo.md
@@ -4,11 +4,12 @@ Display cluster info
 
 ### Synopsis
 
-```
+
 Display addresses of the master and services with label kubernetes.io/cluster-service=true
-```
 
+```
 kubectl clusterinfo
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-config-set-cluster.md b/docs/kubectl-config-set-cluster.md
index 2138d6d5dac0b..106e7203a54a3 100644
--- a/docs/kubectl-config-set-cluster.md
+++ b/docs/kubectl-config-set-cluster.md
@@ -4,16 +4,26 @@ Sets a cluster entry in .kubeconfig
 
 ### Synopsis
 
+
+Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
 ```
-Sets a cluster entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g.
-		kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/.kubernetes.ca.cert
-		only sets the certificate-authority field on the e2e cluster entry without touching other values.
-		
+kubectl config set-cluster NAME [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
+```
+
+### Examples
+
 ```
+// Set only the server field on the e2e cluster entry without touching other values.
+$ kubectl config set-cluster e2e --server=https://1.2.3.4
 
-kubectl config set-cluster name [--server=server] [--certificate-authority=path/to/certficate/authority] [--api-version=apiversion] [--insecure-skip-tls-verify=true]
+// Embed certificate authority data for the e2e cluster entry
+$ kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/kubernetes.ca.crt
+
+// Disable cert checking for the dev cluster entry
+$ kubectl config set-cluster e2e --insecure-skip-tls-verify=true
+```
 
 ### Options
 
diff --git a/docs/kubectl-config-set-context.md b/docs/kubectl-config-set-context.md
index b68f357c4c137..9e4e3062c7cd8 100644
--- a/docs/kubectl-config-set-context.md
+++ b/docs/kubectl-config-set-context.md
@@ -4,15 +4,20 @@ Sets a context entry in .kubeconfig
 
 ### Synopsis
 
-```
+
 Sets a context entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g. 
-		kubectl config set-context gce --user=cluster-admin
-		only sets the user field on the gce context entry without touching other values.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
+
+```
+kubectl config set-context NAME [--cluster=cluster_nickname] [--user=user_nickname] [--namespace=namespace]
 ```
 
-kubectl config set-context name [--cluster=cluster-nickname] [--user=user-nickname] [--namespace=namespace]
+### Examples
+
+```
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set-context gce --user=cluster-admin
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-config-set-credentials.md b/docs/kubectl-config-set-credentials.md
index 0c23a4f020429..a956753902eef 100644
--- a/docs/kubectl-config-set-credentials.md
+++ b/docs/kubectl-config-set-credentials.md
@@ -4,14 +4,9 @@ Sets a user entry in .kubeconfig
 
 ### Synopsis
 
-```
-Sets a user entry in .kubeconfig
-
-  Specifying a name that already exists will merge new fields on top of existing
-  values. For example, the following only sets the "client-key" field on the 
-  "cluster-admin" entry, without touching other values:
 
-    set-credentials cluster-admin --client-key=~/.kube/admin.key
+Sets a user entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values.
 
   Client-certificate flags:
     --client-certificate=certfile --client-key=keyfile
@@ -24,9 +19,24 @@ Sets a user entry in .kubeconfig
 
   Bearer token and basic auth are mutually exclusive.
 
+
+```
+kubectl config set-credentials NAME [--auth-path=/path/to/authfile] [--client-certificate=path/to/certfile] [--client-key=path/to/keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
 ```
 
-kubectl config set-credentials name [--auth-path=authfile] [--client-certificate=certfile] [--client-key=keyfile] [--token=bearer_token] [--username=basic_user] [--password=basic_password]
+### Examples
+
+```
+// Set only the "client-key" field on the "cluster-admin"
+// entry, without touching other values:
+$ kubectl set-credentials cluster-admin --client-key=~/.kube/admin.key
+
+// Set basic auth for the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif
+
+// Embed client certificate data in the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true
+```
 
 ### Options
 
diff --git a/docs/kubectl-config-set.md b/docs/kubectl-config-set.md
index dd86268e84986..1be356a5cb43d 100644
--- a/docs/kubectl-config-set.md
+++ b/docs/kubectl-config-set.md
@@ -4,16 +4,14 @@ Sets an individual value in a .kubeconfig file
 
 ### Synopsis
 
-```
-Sets an individual value in a .kubeconfig file
 
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		property-value is the new value you wish to set.
+Sets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
+PROPERTY_VALUE is the new value you wish to set.
 
-		
 ```
-
-kubectl config set property-name property-value
+kubectl config set PROPERTY_NAME PROPERTY_VALUE
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-config-unset.md b/docs/kubectl-config-unset.md
index 72b00656a0b84..3e327de079004 100644
--- a/docs/kubectl-config-unset.md
+++ b/docs/kubectl-config-unset.md
@@ -4,14 +4,13 @@ Unsets an individual value in a .kubeconfig file
 
 ### Synopsis
 
-```
+
 Unsets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
 
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		
 ```
-
-kubectl config unset property-name
+kubectl config unset PROPERTY_NAME
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-config-use-context.md b/docs/kubectl-config-use-context.md
index 8b152554b3894..11f6e0f7b8825 100644
--- a/docs/kubectl-config-use-context.md
+++ b/docs/kubectl-config-use-context.md
@@ -4,11 +4,12 @@ Sets the current-context in a .kubeconfig file
 
 ### Synopsis
 
-```
+
 Sets the current-context in a .kubeconfig file
-```
 
-kubectl config use-context context-name
+```
+kubectl config use-context CONTEXT_NAME
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-config-view.md b/docs/kubectl-config-view.md
index 037bb63795aee..dd50f1eab8191 100644
--- a/docs/kubectl-config-view.md
+++ b/docs/kubectl-config-view.md
@@ -4,11 +4,14 @@ displays merged .kubeconfig settings or a specified .kubeconfig file.
 
 ### Synopsis
 
-```
+
 displays merged .kubeconfig settings or a specified .kubeconfig file.
-```
 
+You can use --output=template --template=TEMPLATE to extract specific values.
+
+```
 kubectl config view
+```
 
 ### Examples
 
@@ -18,6 +21,9 @@ $ kubectl config view
 
 // Show only local ./.kubeconfig settings
 $ kubectl config view --local
+
+// Get the password for the e2e user
+$ kubectl config view -o template --template='{{ index . "users" "e2e" "password" }}'
 ```
 
 ### Options
diff --git a/docs/kubectl-config.md b/docs/kubectl-config.md
index aac77726be740..56cef264f0b18 100644
--- a/docs/kubectl-config.md
+++ b/docs/kubectl-config.md
@@ -4,11 +4,12 @@ config modifies .kubeconfig files
 
 ### Synopsis
 
-```
+
 config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"
-```
 
-kubectl config <subcommand>
+```
+kubectl config SUBCOMMAND
+```
 
 ### Options
 
diff --git a/docs/kubectl-create.md b/docs/kubectl-create.md
index 63e08787add45..52f8ea32fba93 100644
--- a/docs/kubectl-create.md
+++ b/docs/kubectl-create.md
@@ -4,13 +4,14 @@ Create a resource by filename or stdin
 
 ### Synopsis
 
-```
+
 Create a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl create -f filename
+```
+kubectl create -f FILENAME
+```
 
 ### Examples
 
diff --git a/docs/kubectl-delete.md b/docs/kubectl-delete.md
index 7fa55933b1486..c92da2baeeaa3 100644
--- a/docs/kubectl-delete.md
+++ b/docs/kubectl-delete.md
@@ -4,7 +4,7 @@ Delete a resource by filename, stdin, or resource and ID.
 
 ### Synopsis
 
-```
+
 Delete a resource by filename, stdin, resource and ID, or by resources and label selector.
 
 JSON and YAML formats are accepted.
@@ -15,9 +15,10 @@ arguments are used and the filename is ignored.
 Note that the delete command does NOT do resource version checks, so if someone
 submits an update to a resource right when you submit a delete, their update
 will be lost along with the rest of the resource.
-```
 
-kubectl delete (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl delete ([-f FILENAME] | (RESOURCE [(ID | -l label | --all)]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-describe.md b/docs/kubectl-describe.md
index 5f3ef002074a8..50d0373b78e0e 100644
--- a/docs/kubectl-describe.md
+++ b/docs/kubectl-describe.md
@@ -4,14 +4,15 @@ Show details of a specific resource
 
 ### Synopsis
 
-```
+
 Show details of a specific resource.
 
 This command joins many API calls together to form a detailed description of a
 given resource.
-```
 
-kubectl describe <resource> <id>
+```
+kubectl describe RESOURCE ID
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-exec.md b/docs/kubectl-exec.md
index bd9c921d2c346..3fdda08552a06 100644
--- a/docs/kubectl-exec.md
+++ b/docs/kubectl-exec.md
@@ -4,11 +4,12 @@ Execute a command in a container.
 
 ### Synopsis
 
-```
+
 Execute a command in a container.
-```
 
-kubectl exec -p <pod> -c <container> -- <command> [<args...>]
+```
+kubectl exec -p POD -c CONTAINER -- COMMAND [args...]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-expose.md b/docs/kubectl-expose.md
index 036ff5af90167..e785ddb0954e1 100644
--- a/docs/kubectl-expose.md
+++ b/docs/kubectl-expose.md
@@ -4,14 +4,15 @@ Take a replicated application and expose it as Kubernetes Service
 
 ### Synopsis
 
-```
+
 Take a replicated application and expose it as Kubernetes Service.
-		
+
 Looks up a ReplicationController by name, and uses the selector for that replication controller
 as the selector for a new Service on the specified port.
-```
 
-kubectl expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]
+```
+kubectl expose NAME --port=port [--protocol=TCP|UDP] [--container-port=number-or-name] [--service-name=name] [--public-ip=ip] [--create-external-load-balancer=bool]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-get.md b/docs/kubectl-get.md
index df8b87c4b092e..fcdf18472cd1c 100644
--- a/docs/kubectl-get.md
+++ b/docs/kubectl-get.md
@@ -4,7 +4,7 @@ Display one or many resources
 
 ### Synopsis
 
-```
+
 Display one or many resources.
 
 Possible resources include pods (po), replication controllers (rc), services
@@ -12,9 +12,10 @@ Possible resources include pods (po), replication controllers (rc), services
 
 By specifying the output as 'template' and providing a Go template as the value
 of the --template flag, you can filter the attributes of the fetched resource(s).
-```
 
-kubectl get [(-o|--output=)json|yaml|template|...] <resource> [<id>]
+```
+kubectl get [(-o|--output=)json|yaml|template|...] RESOURCE [ID]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-label.md b/docs/kubectl-label.md
index c4a4f33c17ec2..c3ace001b1c93 100644
--- a/docs/kubectl-label.md
+++ b/docs/kubectl-label.md
@@ -4,14 +4,15 @@ Update the labels on a resource
 
 ### Synopsis
 
-```
+
 Update the labels on a resource.
 
 If --overwrite is true, then existing labels can be overwritten, otherwise attempting to overwrite a label will result in an error.
 If --resource-version is specified, then updates will use this resource version, otherwise the existing resource-version will be used.
-```
 
-kubectl label [--overwrite] <resource> <name> <key-1>=<val-1> ... <key-n>=<val-n> [--resource-version=<version>]
+```
+kubectl label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-log.md b/docs/kubectl-log.md
index ca1a42663fafb..47974b1044784 100644
--- a/docs/kubectl-log.md
+++ b/docs/kubectl-log.md
@@ -4,11 +4,12 @@ Print the logs for a container in a pod.
 
 ### Synopsis
 
-```
+
 Print the logs for a container in a pod. If the pod has only one container, the container name is optional.
-```
 
-kubectl log [-f] <pod> [<container>]
+```
+kubectl log [-f] POD [CONTAINER]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-namespace.md b/docs/kubectl-namespace.md
index 1dde0d85d6b84..e78ae43294d41 100644
--- a/docs/kubectl-namespace.md
+++ b/docs/kubectl-namespace.md
@@ -4,14 +4,15 @@ SUPERCEDED: Set and view the current Kubernetes namespace
 
 ### Synopsis
 
-```
+
 SUPERCEDED:  Set and view the current Kubernetes namespace scope for command line requests.
 
 namespace has been superceded by the context.namespace field of .kubeconfig files.  See 'kubectl config set-context --help' for more details.
 
-```
 
-kubectl namespace [<namespace>]
+```
+kubectl namespace [namespace]
+```
 
 ### Options inherrited from parent commands
 
diff --git a/docs/kubectl-port-forward.md b/docs/kubectl-port-forward.md
index fb7fe546821da..468dc2356efe4 100644
--- a/docs/kubectl-port-forward.md
+++ b/docs/kubectl-port-forward.md
@@ -4,26 +4,28 @@ Forward 1 or more local ports to a pod.
 
 ### Synopsis
 
-```
+
 Forward 1 or more local ports to a pod.
-```
 
-kubectl port-forward -p <pod> [<local port>:]<remote port> [<port>...]
+```
+kubectl port-forward -p POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]
+```
 
 ### Examples
 
 ```
+
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
 $ kubectl port-forward -p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> 
 ```
 
 ### Options
diff --git a/docs/kubectl-proxy.md b/docs/kubectl-proxy.md
index 67e775b22ce4f..e8f2a0d5c4888 100644
--- a/docs/kubectl-proxy.md
+++ b/docs/kubectl-proxy.md
@@ -4,11 +4,23 @@ Run a proxy to the Kubernetes API server
 
 ### Synopsis
 
+
+Run a proxy to the Kubernetes API server. 
+
+```
+kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]
 ```
-Run a proxy to the Kubernetes API server.
+
+### Examples
+
 ```
+// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy --port=8011 --www=./local/www/
 
-kubectl proxy
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s-api
+// This makes e.g. the pods api available at localhost:8011/k8s-api/v1beta1/pods/
+$ kubectl proxy --api-prefix=k8s-api
+```
 
 ### Options
 
diff --git a/docs/kubectl-resize.md b/docs/kubectl-resize.md
index a11b7294b4828..d528aecf1d800 100644
--- a/docs/kubectl-resize.md
+++ b/docs/kubectl-resize.md
@@ -4,16 +4,17 @@ Set a new size for a Replication Controller.
 
 ### Synopsis
 
-```
+
 Set a new size for a Replication Controller.
 
 Resize also allows users to specify one or more preconditions for the resize action.
 If --current-replicas or --resource-version is specified, it is validated before the
 resize is attempted, and it is guaranteed that the precondition holds true when the
 resize is sent to the server.
-```
 
-kubectl resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>
+```
+kubectl resize [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE ID
+```
 
 ### Examples
 
diff --git a/docs/kubectl-rollingupdate.md b/docs/kubectl-rollingupdate.md
index 591758df797b0..9f0c33a6dcfc8 100644
--- a/docs/kubectl-rollingupdate.md
+++ b/docs/kubectl-rollingupdate.md
@@ -4,15 +4,16 @@ Perform a rolling update of the given ReplicationController.
 
 ### Synopsis
 
-```
+
 Perform a rolling update of the given ReplicationController.
 
 Replaces the specified controller with new controller, updating one pod at a time to use the
 new PodTemplate. The new-controller.json must specify the same namespace as the
 existing controller and overwrite at least one (common) label in its replicaSelector.
-```
 
-kubectl rollingupdate <old-controller-name> -f <new-controller.json>
+```
+kubectl rollingupdate OLD_CONTROLLER_NAME -f NEW_CONTROLLER_SPEC
+```
 
 ### Examples
 
diff --git a/docs/kubectl-run-container.md b/docs/kubectl-run-container.md
index a4fa016a0fd89..da469a69ce535 100644
--- a/docs/kubectl-run-container.md
+++ b/docs/kubectl-run-container.md
@@ -4,12 +4,13 @@ Run a particular image on the cluster.
 
 ### Synopsis
 
-```
+
 Create and run a particular image, possibly replicated.
 Creates a replication controller to manage the created container(s).
-```
 
-kubectl run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]
+```
+kubectl run-container NAME --image=image [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]
+```
 
 ### Examples
 
diff --git a/docs/kubectl-stop.md b/docs/kubectl-stop.md
index 05ebc70c701f4..2a56f2ea19699 100644
--- a/docs/kubectl-stop.md
+++ b/docs/kubectl-stop.md
@@ -4,14 +4,15 @@ Gracefully shut down a resource by id or filename.
 
 ### Synopsis
 
-```
+
 Gracefully shut down a resource by id or filename.
 
 Attempts to shut down and delete a resource that supports graceful termination.
 If the resource is resizable it will be resized to 0 before deletion.
-```
 
-kubectl stop (-f filename | <resource> (<id> | -l <label> | --all))
+```
+kubectl stop (-f FILENAME | RESOURCE (ID | -l label | --all))
+```
 
 ### Examples
 
diff --git a/docs/kubectl-update.md b/docs/kubectl-update.md
index ed0c24191e9a7..be76088fc6188 100644
--- a/docs/kubectl-update.md
+++ b/docs/kubectl-update.md
@@ -4,13 +4,14 @@ Update a resource by filename or stdin.
 
 ### Synopsis
 
-```
+
 Update a resource by filename or stdin.
 
 JSON and YAML formats are accepted.
-```
 
-kubectl update -f filename
+```
+kubectl update -f FILENAME
+```
 
 ### Examples
 
diff --git a/docs/kubectl-version.md b/docs/kubectl-version.md
index d990155fb3908..9dadaa4910ec0 100644
--- a/docs/kubectl-version.md
+++ b/docs/kubectl-version.md
@@ -4,11 +4,12 @@ Print the client and server version information.
 
 ### Synopsis
 
-```
+
 Print the client and server version information.
-```
 
+```
 kubectl version
+```
 
 ### Options
 
diff --git a/docs/kubectl.md b/docs/kubectl.md
index 6edec67d945fb..031cbd0fa14b1 100644
--- a/docs/kubectl.md
+++ b/docs/kubectl.md
@@ -4,13 +4,14 @@ kubectl controls the Kubernetes cluster manager
 
 ### Synopsis
 
-```
+
 kubectl controls the Kubernetes cluster manager.
 
 Find more information at https://github.com/GoogleCloudPlatform/kubernetes.
-```
 
+```
 kubectl
+```
 
 ### Options
 
diff --git a/docs/man/man1/kubectl-config-set-cluster.1 b/docs/man/man1/kubectl-config-set-cluster.1
index e6106ddf150ec..b10b169fc2f0a 100644
--- a/docs/man/man1/kubectl-config-set-cluster.1
+++ b/docs/man/man1/kubectl-config-set-cluster.1
@@ -13,11 +13,8 @@ kubectl config set\-cluster \- Sets a cluster entry in .kubeconfig
 
 .SH DESCRIPTION
 .PP
-Sets a cluster entry in .kubeconfig
-    Specifying a name that already exists will merge new fields on top of existing values for those fields.
-    e.g.
-        kubectl config set\-cluster e2e \-\-certificate\-authority=\~/.kube/e2e/.kubernetes.ca.cert
-        only sets the certificate\-authority field on the e2e cluster entry without touching other values.
+Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
 
 
 .SH OPTIONS
@@ -144,6 +141,24 @@ Sets a cluster entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Set only the server field on the e2e cluster entry without touching other values.
+$ kubectl config set\-cluster e2e \-\-server=https://1.2.3.4
+
+// Embed certificate authority data for the e2e cluster entry
+$ kubectl config set\-cluster e2e \-\-certificate\-authority=\~/.kube/e2e/kubernetes.ca.crt
+
+// Disable cert checking for the dev cluster entry
+$ kubectl config set\-cluster e2e \-\-insecure\-skip\-tls\-verify=true
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,
diff --git a/docs/man/man1/kubectl-config-set-context.1 b/docs/man/man1/kubectl-config-set-context.1
index fa5ff1874e064..5f2795b6f753f 100644
--- a/docs/man/man1/kubectl-config-set-context.1
+++ b/docs/man/man1/kubectl-config-set-context.1
@@ -14,10 +14,7 @@ kubectl config set\-context \- Sets a context entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 Sets a context entry in .kubeconfig
-    Specifying a name that already exists will merge new fields on top of existing values for those fields.
-    e.g.
-        kubectl config set\-context gce \-\-user=cluster\-admin
-        only sets the user field on the gce context entry without touching other values.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
@@ -138,6 +135,18 @@ Sets a context entry in .kubeconfig
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Set the user field on the gce context entry without touching other values
+$ kubectl config set\-context gce \-\-user=cluster\-admin
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,
diff --git a/docs/man/man1/kubectl-config-set-credentials.1 b/docs/man/man1/kubectl-config-set-credentials.1
index b2b62dd32f0fe..2774c4711491c 100644
--- a/docs/man/man1/kubectl-config-set-credentials.1
+++ b/docs/man/man1/kubectl-config-set-credentials.1
@@ -14,20 +14,7 @@ kubectl config set\-credentials \- Sets a user entry in .kubeconfig
 .SH DESCRIPTION
 .PP
 Sets a user entry in .kubeconfig
-
-.PP
-Specifying a name that already exists will merge new fields on top of existing
-  values. For example, the following only sets the "client\-key" field on the
-  "cluster\-admin" entry, without touching other values:
-
-.PP
-.RS
-
-.nf
-set\-credentials cluster\-admin \-\-client\-key=\~/.kube/admin.key
-
-.fi
-.RE
+Specifying a name that already exists will merge new fields on top of existing values.
 
 .PP
 Client\-certificate flags:
@@ -169,6 +156,25 @@ Bearer token and basic auth are mutually exclusive.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Set only the "client\-key" field on the "cluster\-admin"
+// entry, without touching other values:
+$ kubectl set\-credentials cluster\-admin \-\-client\-key=\~/.kube/admin.key
+
+// Set basic auth for the "cluster\-admin" entry
+$ kubectl set\-credentials cluster\-admin \-\-username=admin \-\-password=uXFGweU9l35qcif
+
+// Embed client certificate data in the "cluster\-admin" entry
+$ kubectl set\-credentials cluster\-admin \-\-client\-certificate=\~/.kube/admin.crt \-\-embed\-certs=true
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl\-config(1)\fP,
diff --git a/docs/man/man1/kubectl-config-set.1 b/docs/man/man1/kubectl-config-set.1
index 9369dc12e8ce2..eb854db0ff925 100644
--- a/docs/man/man1/kubectl-config-set.1
+++ b/docs/man/man1/kubectl-config-set.1
@@ -14,16 +14,8 @@ kubectl config set \- Sets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Sets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    property\-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-    property\-value is the new value you wish to set.
-
-.fi
-.RE
+PROPERTY\_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
+PROPERTY\_VALUE is the new value you wish to set.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
diff --git a/docs/man/man1/kubectl-config-unset.1 b/docs/man/man1/kubectl-config-unset.1
index e61c16ab202e0..76cf676c374bb 100644
--- a/docs/man/man1/kubectl-config-unset.1
+++ b/docs/man/man1/kubectl-config-unset.1
@@ -14,15 +14,7 @@ kubectl config unset \- Unsets an individual value in a .kubeconfig file
 .SH DESCRIPTION
 .PP
 Unsets an individual value in a .kubeconfig file
-
-.PP
-.RS
-
-.nf
-    property\-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-
-.fi
-.RE
+PROPERTY\_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
 
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
diff --git a/docs/man/man1/kubectl-config-view.1 b/docs/man/man1/kubectl-config-view.1
index 8577af8ab7b4f..2d64119a44ce8 100644
--- a/docs/man/man1/kubectl-config-view.1
+++ b/docs/man/man1/kubectl-config-view.1
@@ -15,6 +15,9 @@ kubectl config view \- displays merged .kubeconfig settings or a specified .kube
 .PP
 displays merged .kubeconfig settings or a specified .kubeconfig file.
 
+.PP
+You can use \-\-output=template \-\-template=TEMPLATE to extract specific values.
+
 
 .SH OPTIONS
 .PP
@@ -168,6 +171,9 @@ $ kubectl config view
 // Show only local ./.kubeconfig settings
 $ kubectl config view \-\-local
 
+// Get the password for the e2e user
+$ kubectl config view \-o template \-\-template='\{\{ index . "users" "e2e" "password" \}\}'
+
 .fi
 .RE
 
diff --git a/docs/man/man1/kubectl-port-forward.1 b/docs/man/man1/kubectl-port-forward.1
index 4c1e3449e58f4..912ce1e9e562a 100644
--- a/docs/man/man1/kubectl-port-forward.1
+++ b/docs/man/man1/kubectl-port-forward.1
@@ -133,17 +133,18 @@ Forward 1 or more local ports to a pod.
 .RS
 
 .nf
+
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
 $ kubectl port\-forward \-p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port\-forward \-p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> 
 
 .fi
 .RE
diff --git a/docs/man/man1/kubectl-proxy.1 b/docs/man/man1/kubectl-proxy.1
index cba3fac411aaf..a7fda879767f1 100644
--- a/docs/man/man1/kubectl-proxy.1
+++ b/docs/man/man1/kubectl-proxy.1
@@ -140,6 +140,22 @@ Run a proxy to the Kubernetes API server.
     comma\-separated list of pattern=N settings for file\-filtered logging
 
 
+.SH EXAMPLE
+.PP
+.RS
+
+.nf
+// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy \-\-port=8011 \-\-www=./local/www/
+
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s\-api
+// This makes e.g. the pods api available at localhost:8011/k8s\-api/v1beta1/pods/
+$ kubectl proxy \-\-api\-prefix=k8s\-api
+
+.fi
+.RE
+
+
 .SH SEE ALSO
 .PP
 \fBkubectl(1)\fP,
diff --git a/pkg/kubectl/cmd/config/config.go b/pkg/kubectl/cmd/config/config.go
index dca868c0e30bc..8ec9632809a04 100644
--- a/pkg/kubectl/cmd/config/config.go
+++ b/pkg/kubectl/cmd/config/config.go
@@ -40,7 +40,7 @@ func NewCmdConfig(out io.Writer) *cobra.Command {
 	pathOptions := &pathOptions{}
 
 	cmd := &cobra.Command{
-		Use:   "config <subcommand>",
+		Use:   "config SUBCOMMAND",
 		Short: "config modifies .kubeconfig files",
 		Long:  `config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context"`,
 		Run: func(cmd *cobra.Command, args []string) {
diff --git a/pkg/kubectl/cmd/config/create_authinfo.go b/pkg/kubectl/cmd/config/create_authinfo.go
index 114daaefed3fa..8253e350a5a69 100644
--- a/pkg/kubectl/cmd/config/create_authinfo.go
+++ b/pkg/kubectl/cmd/config/create_authinfo.go
@@ -42,19 +42,8 @@ type createAuthInfoOptions struct {
 	embedCertData     util.BoolFlag
 }
 
-func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Command {
-	options := &createAuthInfoOptions{pathOptions: pathOptions}
-
-	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-credentials name [--%v=authfile] [--%v=certfile] [--%v=keyfile] [--%v=bearer_token] [--%v=basic_user] [--%v=basic_password]", clientcmd.FlagAuthPath, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
-		Short: "Sets a user entry in .kubeconfig",
-		Long: fmt.Sprintf(`Sets a user entry in .kubeconfig
-
-  Specifying a name that already exists will merge new fields on top of existing
-  values. For example, the following only sets the "client-key" field on the 
-  "cluster-admin" entry, without touching other values:
-
-    set-credentials cluster-admin --client-key=~/.kube/admin.key
+var create_authinfo_long = fmt.Sprintf(`Sets a user entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values.
 
   Client-certificate flags:
     --%v=certfile --%v=keyfile
@@ -66,7 +55,26 @@ func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Com
     --%v=basic_user --%v=basic_password
 
   Bearer token and basic auth are mutually exclusive.
-`, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
+`, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword)
+
+const create_authinfo_example = `// Set only the "client-key" field on the "cluster-admin"
+// entry, without touching other values:
+$ kubectl set-credentials cluster-admin --client-key=~/.kube/admin.key
+
+// Set basic auth for the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --username=admin --password=uXFGweU9l35qcif
+
+// Embed client certificate data in the "cluster-admin" entry
+$ kubectl set-credentials cluster-admin --client-certificate=~/.kube/admin.crt --embed-certs=true`
+
+func NewCmdConfigSetAuthInfo(out io.Writer, pathOptions *pathOptions) *cobra.Command {
+	options := &createAuthInfoOptions{pathOptions: pathOptions}
+
+	cmd := &cobra.Command{
+		Use:     fmt.Sprintf("set-credentials NAME [--%v=/path/to/authfile] [--%v=path/to/certfile] [--%v=path/to/keyfile] [--%v=bearer_token] [--%v=basic_user] [--%v=basic_password]", clientcmd.FlagAuthPath, clientcmd.FlagCertFile, clientcmd.FlagKeyFile, clientcmd.FlagBearerToken, clientcmd.FlagUsername, clientcmd.FlagPassword),
+		Short:   "Sets a user entry in .kubeconfig",
+		Long:    create_authinfo_long,
+		Example: create_authinfo_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return
diff --git a/pkg/kubectl/cmd/config/create_cluster.go b/pkg/kubectl/cmd/config/create_cluster.go
index 558cc97365664..08c38361b20d1 100644
--- a/pkg/kubectl/cmd/config/create_cluster.go
+++ b/pkg/kubectl/cmd/config/create_cluster.go
@@ -39,18 +39,27 @@ type createClusterOptions struct {
 	embedCAData           util.BoolFlag
 }
 
+const (
+	create_cluster_long = `Sets a cluster entry in .kubeconfig.
+Specifying a name that already exists will merge new fields on top of existing values for those fields.`
+	create_cluster_example = `// Set only the server field on the e2e cluster entry without touching other values.
+$ kubectl config set-cluster e2e --server=https://1.2.3.4
+
+// Embed certificate authority data for the e2e cluster entry
+$ kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/kubernetes.ca.crt
+
+// Disable cert checking for the dev cluster entry
+$ kubectl config set-cluster e2e --insecure-skip-tls-verify=true`
+)
+
 func NewCmdConfigSetCluster(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &createClusterOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-cluster name [--%v=server] [--%v=path/to/certficate/authority] [--%v=apiversion] [--%v=true]", clientcmd.FlagAPIServer, clientcmd.FlagCAFile, clientcmd.FlagAPIVersion, clientcmd.FlagInsecure),
-		Short: "Sets a cluster entry in .kubeconfig",
-		Long: `Sets a cluster entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g.
-		kubectl config set-cluster e2e --certificate-authority=~/.kube/e2e/.kubernetes.ca.cert
-		only sets the certificate-authority field on the e2e cluster entry without touching other values.
-		`,
+		Use:     fmt.Sprintf("set-cluster NAME [--%v=server] [--%v=path/to/certficate/authority] [--%v=apiversion] [--%v=true]", clientcmd.FlagAPIServer, clientcmd.FlagCAFile, clientcmd.FlagAPIVersion, clientcmd.FlagInsecure),
+		Short:   "Sets a cluster entry in .kubeconfig",
+		Long:    create_cluster_long,
+		Example: create_cluster_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return
diff --git a/pkg/kubectl/cmd/config/create_context.go b/pkg/kubectl/cmd/config/create_context.go
index aac3d588a26a3..3869e28cf5568 100644
--- a/pkg/kubectl/cmd/config/create_context.go
+++ b/pkg/kubectl/cmd/config/create_context.go
@@ -36,18 +36,21 @@ type createContextOptions struct {
 	namespace   util.StringFlag
 }
 
+const (
+	create_context_long = `Sets a context entry in .kubeconfig
+Specifying a name that already exists will merge new fields on top of existing values for those fields.`
+	create_context_example = `// Set the user field on the gce context entry without touching other values
+$ kubectl config set-context gce --user=cluster-admin`
+)
+
 func NewCmdConfigSetContext(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &createContextOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("set-context name [--%v=cluster-nickname] [--%v=user-nickname] [--%v=namespace]", clientcmd.FlagClusterName, clientcmd.FlagAuthInfoName, clientcmd.FlagNamespace),
-		Short: "Sets a context entry in .kubeconfig",
-		Long: `Sets a context entry in .kubeconfig
-	Specifying a name that already exists will merge new fields on top of existing values for those fields.
-	e.g. 
-		kubectl config set-context gce --user=cluster-admin
-		only sets the user field on the gce context entry without touching other values.`,
-
+		Use:     fmt.Sprintf("set-context NAME [--%v=cluster_nickname] [--%v=user_nickname] [--%v=namespace]", clientcmd.FlagClusterName, clientcmd.FlagAuthInfoName, clientcmd.FlagNamespace),
+		Short:   "Sets a context entry in .kubeconfig",
+		Long:    create_context_long,
+		Example: create_context_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return
diff --git a/pkg/kubectl/cmd/config/set.go b/pkg/kubectl/cmd/config/set.go
index ab11aaeb731e8..b65a00f9d91a5 100644
--- a/pkg/kubectl/cmd/config/set.go
+++ b/pkg/kubectl/cmd/config/set.go
@@ -39,18 +39,17 @@ type setOptions struct {
 	propertyValue string
 }
 
+const set_long = `Sets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
+PROPERTY_VALUE is the new value you wish to set.`
+
 func NewCmdConfigSet(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &setOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "set property-name property-value",
+		Use:   "set PROPERTY_NAME PROPERTY_VALUE",
 		Short: "Sets an individual value in a .kubeconfig file",
-		Long: `Sets an individual value in a .kubeconfig file
-
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		property-value is the new value you wish to set.
-
-		`,
+		Long:  set_long,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return
diff --git a/pkg/kubectl/cmd/config/unset.go b/pkg/kubectl/cmd/config/unset.go
index d04a82a933e9b..d0fda6a3e5661 100644
--- a/pkg/kubectl/cmd/config/unset.go
+++ b/pkg/kubectl/cmd/config/unset.go
@@ -32,16 +32,16 @@ type unsetOptions struct {
 	propertyName string
 }
 
+const unset_long = `Unsets an individual value in a .kubeconfig file
+PROPERTY_NAME is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.`
+
 func NewCmdConfigUnset(out io.Writer, pathOptions *pathOptions) *cobra.Command {
 	options := &unsetOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "unset property-name",
+		Use:   "unset PROPERTY_NAME",
 		Short: "Unsets an individual value in a .kubeconfig file",
-		Long: `Unsets an individual value in a .kubeconfig file
-
-		property-name is a dot delimited name where each token represents either a attribute name or a map key.  Map keys may not contain dots.
-		`,
+		Long:  unset_long,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return
diff --git a/pkg/kubectl/cmd/config/use_context.go b/pkg/kubectl/cmd/config/use_context.go
index 1ac50fef1d30a..0508fd1b70710 100644
--- a/pkg/kubectl/cmd/config/use_context.go
+++ b/pkg/kubectl/cmd/config/use_context.go
@@ -35,7 +35,7 @@ func NewCmdConfigUseContext(out io.Writer, pathOptions *pathOptions) *cobra.Comm
 	options := &useContextOptions{pathOptions: pathOptions}
 
 	cmd := &cobra.Command{
-		Use:   "use-context context-name",
+		Use:   "use-context CONTEXT_NAME",
 		Short: "Sets the current-context in a .kubeconfig file",
 		Long:  `Sets the current-context in a .kubeconfig file`,
 		Run: func(cmd *cobra.Command, args []string) {
diff --git a/pkg/kubectl/cmd/config/view.go b/pkg/kubectl/cmd/config/view.go
index 434cc2c9b3d1b..82cf3f83a7675 100644
--- a/pkg/kubectl/cmd/config/view.go
+++ b/pkg/kubectl/cmd/config/view.go
@@ -35,18 +35,28 @@ type viewOptions struct {
 	merge       util.BoolFlag
 }
 
-func NewCmdConfigView(out io.Writer, pathOptions *pathOptions) *cobra.Command {
-	options := &viewOptions{pathOptions: pathOptions}
+const (
+	view_long = `displays merged .kubeconfig settings or a specified .kubeconfig file.
 
-	cmd := &cobra.Command{
-		Use:   "view",
-		Short: "displays merged .kubeconfig settings or a specified .kubeconfig file.",
-		Long:  "displays merged .kubeconfig settings or a specified .kubeconfig file.",
-		Example: `// Show merged .kubeconfig settings.
+You can use --output=template --template=TEMPLATE to extract specific values.`
+	view_example = `// Show merged .kubeconfig settings.
 $ kubectl config view
 
 // Show only local ./.kubeconfig settings
-$ kubectl config view --local`,
+$ kubectl config view --local
+
+// Get the password for the e2e user
+$ kubectl config view -o template --template='{{ index . "users" "e2e" "password" }}'`
+)
+
+func NewCmdConfigView(out io.Writer, pathOptions *pathOptions) *cobra.Command {
+	options := &viewOptions{pathOptions: pathOptions}
+
+	cmd := &cobra.Command{
+		Use:     "view",
+		Short:   "displays merged .kubeconfig settings or a specified .kubeconfig file.",
+		Long:    view_long,
+		Example: view_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			options.complete()
 
diff --git a/pkg/kubectl/cmd/create.go b/pkg/kubectl/cmd/create.go
index c006d06778061..1ce0e7a686eea 100644
--- a/pkg/kubectl/cmd/create.go
+++ b/pkg/kubectl/cmd/create.go
@@ -41,7 +41,7 @@ $ cat pod.json | kubectl create -f -`
 func (f *Factory) NewCmdCreate(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "create -f filename",
+		Use:     "create -f FILENAME",
 		Short:   "Create a resource by filename or stdin",
 		Long:    create_long,
 		Example: create_example,
diff --git a/pkg/kubectl/cmd/delete.go b/pkg/kubectl/cmd/delete.go
index a215ab1235bee..1770ce644681d 100644
--- a/pkg/kubectl/cmd/delete.go
+++ b/pkg/kubectl/cmd/delete.go
@@ -58,7 +58,7 @@ $ kubectl delete pods --all`
 func (f *Factory) NewCmdDelete(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "delete (-f filename | <resource> (<id> | -l <label> | --all))",
+		Use:     "delete ([-f FILENAME] | (RESOURCE [(ID | -l label | --all)]",
 		Short:   "Delete a resource by filename, stdin, or resource and ID.",
 		Long:    delete_long,
 		Example: delete_example,
diff --git a/pkg/kubectl/cmd/describe.go b/pkg/kubectl/cmd/describe.go
index 9a9a3052fbe63..6b612af9bde6f 100644
--- a/pkg/kubectl/cmd/describe.go
+++ b/pkg/kubectl/cmd/describe.go
@@ -26,7 +26,7 @@ import (
 
 func (f *Factory) NewCmdDescribe(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "describe <resource> <id>",
+		Use:   "describe RESOURCE ID",
 		Short: "Show details of a specific resource",
 		Long: `Show details of a specific resource.
 
diff --git a/pkg/kubectl/cmd/exec.go b/pkg/kubectl/cmd/exec.go
index 907e0eb425606..dd825d25d43d9 100644
--- a/pkg/kubectl/cmd/exec.go
+++ b/pkg/kubectl/cmd/exec.go
@@ -40,7 +40,7 @@ $ kubectl exec -p 123456-7890 -c ruby-container -i -t -- bash -il`
 
 func (f *Factory) NewCmdExec(cmdIn io.Reader, cmdOut, cmdErr io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "exec -p <pod> -c <container> -- <command> [<args...>]",
+		Use:     "exec -p POD -c CONTAINER -- COMMAND [args...]",
 		Short:   "Execute a command in a container.",
 		Long:    "Execute a command in a container.",
 		Example: exec_example,
@@ -60,11 +60,11 @@ func (f *Factory) NewCmdExec(cmdIn io.Reader, cmdOut, cmdErr io.Writer) *cobra.C
 func RunExec(f *Factory, cmdIn io.Reader, cmdOut, cmdErr io.Writer, cmd *cobra.Command, args []string) error {
 	podName := util.GetFlagString(cmd, "pod")
 	if len(podName) == 0 {
-		return util.UsageError(cmd, "<pod> is required for exec")
+		return util.UsageError(cmd, "POD is required for exec")
 	}
 
 	if len(args) < 1 {
-		return util.UsageError(cmd, "<command> is required for exec")
+		return util.UsageError(cmd, "COMMAND is required for exec")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)
diff --git a/pkg/kubectl/cmd/expose.go b/pkg/kubectl/cmd/expose.go
index 6ca250ffd8cfa..2b779edeb9d3e 100644
--- a/pkg/kubectl/cmd/expose.go
+++ b/pkg/kubectl/cmd/expose.go
@@ -28,7 +28,7 @@ import (
 
 const (
 	expose_long = `Take a replicated application and expose it as Kubernetes Service.
-		
+
 Looks up a ReplicationController by name, and uses the selector for that replication controller
 as the selector for a new Service on the specified port.`
 
@@ -41,7 +41,7 @@ $ kubectl expose streamer --port=4100 --protocol=udp --service-name=video-stream
 
 func (f *Factory) NewCmdExposeService(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "expose <name> --port=<port> [--protocol=TCP|UDP] [--container-port=<number-or-name>] [--service-name=<name>] [--public-ip=<ip>] [--create-external-load-balancer]",
+		Use:     "expose NAME --port=port [--protocol=TCP|UDP] [--container-port=number-or-name] [--service-name=name] [--public-ip=ip] [--create-external-load-balancer=bool]",
 		Short:   "Take a replicated application and expose it as Kubernetes Service",
 		Long:    expose_long,
 		Example: expose_example,
diff --git a/pkg/kubectl/cmd/get.go b/pkg/kubectl/cmd/get.go
index 9af9758b2ca3b..8f9e1ed0fbdd7 100644
--- a/pkg/kubectl/cmd/get.go
+++ b/pkg/kubectl/cmd/get.go
@@ -58,7 +58,7 @@ $ kubectl get rc,services`
 // retrieves one or more resources from a server.
 func (f *Factory) NewCmdGet(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "get [(-o|--output=)json|yaml|template|...] <resource> [<id>]",
+		Use:     "get [(-o|--output=)json|yaml|template|...] RESOURCE [ID]",
 		Short:   "Display one or many resources",
 		Long:    get_long,
 		Example: get_example,
diff --git a/pkg/kubectl/cmd/label.go b/pkg/kubectl/cmd/label.go
index 1874829b0302e..53619a62d05c7 100644
--- a/pkg/kubectl/cmd/label.go
+++ b/pkg/kubectl/cmd/label.go
@@ -50,7 +50,7 @@ $ kubectl label pods foo bar-`
 
 func (f *Factory) NewCmdLabel(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "label [--overwrite] <resource> <name> <key-1>=<val-1> ... <key-n>=<val-n> [--resource-version=<version>]",
+		Use:     "label [--overwrite] RESOURCE NAME KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]",
 		Short:   "Update the labels on a resource",
 		Long:    label_long,
 		Example: label_example,
diff --git a/pkg/kubectl/cmd/log.go b/pkg/kubectl/cmd/log.go
index e21a464ad08a4..733460e693adb 100644
--- a/pkg/kubectl/cmd/log.go
+++ b/pkg/kubectl/cmd/log.go
@@ -59,7 +59,7 @@ func selectContainer(pod *api.Pod, in io.Reader, out io.Writer) string {
 
 func (f *Factory) NewCmdLog(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "log [-f] <pod> [<container>]",
+		Use:     "log [-f] POD [CONTAINER]",
 		Short:   "Print the logs for a container in a pod.",
 		Long:    "Print the logs for a container in a pod. If the pod has only one container, the container name is optional.",
 		Example: log_example,
@@ -75,11 +75,11 @@ func (f *Factory) NewCmdLog(out io.Writer) *cobra.Command {
 
 func RunLog(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	if len(args) == 0 {
-		return util.UsageError(cmd, "<pod> is required for log")
+		return util.UsageError(cmd, "POD is required for log")
 	}
 
 	if len(args) > 2 {
-		return util.UsageError(cmd, "log <pod> [<container>]")
+		return util.UsageError(cmd, "log POD [CONTAINER]")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)
diff --git a/pkg/kubectl/cmd/namespace.go b/pkg/kubectl/cmd/namespace.go
index d70d0b1387fb9..1a63eb538614c 100644
--- a/pkg/kubectl/cmd/namespace.go
+++ b/pkg/kubectl/cmd/namespace.go
@@ -27,7 +27,7 @@ import (
 // TODO remove once people have been given enough time to notice
 func NewCmdNamespace(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "namespace [<namespace>]",
+		Use:   "namespace [namespace]",
 		Short: "SUPERCEDED: Set and view the current Kubernetes namespace",
 		Long: `SUPERCEDED:  Set and view the current Kubernetes namespace scope for command line requests.
 
diff --git a/pkg/kubectl/cmd/portforward.go b/pkg/kubectl/cmd/portforward.go
index af00bbe2a4cc7..52490e57ad9a7 100644
--- a/pkg/kubectl/cmd/portforward.go
+++ b/pkg/kubectl/cmd/portforward.go
@@ -28,22 +28,23 @@ import (
 )
 
 const (
-	portforward_example = `$ kubectl port-forward -p mypod 5000 6000
-<listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod>
+	portforward_example = `
+// listens on ports 5000 and 6000 locally, forwarding data to/from ports 5000 and 6000 in the pod
+$ kubectl port-forward -p mypod 5000 6000
 
+// listens on port 8888 locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod 8888:5000
-<listens on port 8888 locally, forwarding to 5000 in the pod>
 
+// listens on a random port locally, forwarding to 5000 in the pod
 $ kubectl port-forward -p mypod :5000
-<listens on a random port locally, forwarding to 5000 in the pod>
 
-$ kubectl port-forward -p mypod 0:5000
-<listens on a random port locally, forwarding to 5000 in the pod> `
+// listens on a random port locally, forwarding to 5000 in the pod
+$ kubectl port-forward -p mypod 0:5000`
 )
 
 func (f *Factory) NewCmdPortForward() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "port-forward -p <pod> [<local port>:]<remote port> [<port>...]",
+		Use:     "port-forward -p POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]",
 		Short:   "Forward 1 or more local ports to a pod.",
 		Long:    "Forward 1 or more local ports to a pod.",
 		Example: portforward_example,
@@ -60,11 +61,11 @@ func (f *Factory) NewCmdPortForward() *cobra.Command {
 func RunPortForward(f *Factory, cmd *cobra.Command, args []string) error {
 	podName := util.GetFlagString(cmd, "pod")
 	if len(podName) == 0 {
-		return util.UsageError(cmd, "<pod> is required for exec")
+		return util.UsageError(cmd, "POD is required for exec")
 	}
 
 	if len(args) < 1 {
-		return util.UsageError(cmd, "at least 1 <port> is required for port-forward")
+		return util.UsageError(cmd, "at least 1 PORT is required for port-forward")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)
diff --git a/pkg/kubectl/cmd/proxy.go b/pkg/kubectl/cmd/proxy.go
index 079001aceb190..1051d23fed90b 100644
--- a/pkg/kubectl/cmd/proxy.go
+++ b/pkg/kubectl/cmd/proxy.go
@@ -27,11 +27,21 @@ import (
 	"github.com/spf13/cobra"
 )
 
+const (
+	proxy_example = `// Run a proxy to kubernetes apiserver on port 8011, serving static content from ./local/www/
+$ kubectl proxy --port=8011 --www=./local/www/
+
+// Run a proxy to kubernetes apiserver, changing the api prefix to k8s-api
+// This makes e.g. the pods api available at localhost:8011/k8s-api/v1beta1/pods/
+$ kubectl proxy --api-prefix=k8s-api`
+)
+
 func (f *Factory) NewCmdProxy(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "proxy",
-		Short: "Run a proxy to the Kubernetes API server",
-		Long:  `Run a proxy to the Kubernetes API server.`,
+		Use:     "proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]",
+		Short:   "Run a proxy to the Kubernetes API server",
+		Long:    `Run a proxy to the Kubernetes API server. `,
+		Example: proxy_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunProxy(f, out, cmd)
 			util.CheckErr(err)
diff --git a/pkg/kubectl/cmd/resize.go b/pkg/kubectl/cmd/resize.go
index f126b8b7cb803..06bb46a02f9aa 100644
--- a/pkg/kubectl/cmd/resize.go
+++ b/pkg/kubectl/cmd/resize.go
@@ -47,7 +47,7 @@ $ kubectl resize --current-replicas=2 --replicas=3 replicationcontrollers foo`
 
 func (f *Factory) NewCmdResize(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "resize [--resource-version=<version>] [--current-replicas=<count>] --replicas=<count> <resource> <id>",
+		Use:     "resize [--resource-version=version] [--current-replicas=count] --replicas=COUNT RESOURCE ID",
 		Short:   "Set a new size for a Replication Controller.",
 		Long:    resize_long,
 		Example: resize_example,
@@ -65,7 +65,7 @@ func (f *Factory) NewCmdResize(out io.Writer) *cobra.Command {
 func RunResize(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	count := util.GetFlagInt(cmd, "replicas")
 	if len(args) != 2 || count < 0 {
-		return util.UsageError(cmd, "--replicas=<count> <resource> <id>")
+		return util.UsageError(cmd, "--replicas=COUNT RESOURCE ID")
 	}
 
 	cmdNamespace, err := f.DefaultNamespace(cmd)
diff --git a/pkg/kubectl/cmd/rollingupdate.go b/pkg/kubectl/cmd/rollingupdate.go
index 933a5381db9ff..459c785462050 100644
--- a/pkg/kubectl/cmd/rollingupdate.go
+++ b/pkg/kubectl/cmd/rollingupdate.go
@@ -44,7 +44,7 @@ $ cat frontend-v2.json | kubectl rollingupdate frontend-v1 -f -`
 
 func (f *Factory) NewCmdRollingUpdate(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "rollingupdate <old-controller-name> -f <new-controller.json>",
+		Use:     "rollingupdate OLD_CONTROLLER_NAME -f NEW_CONTROLLER_SPEC",
 		Short:   "Perform a rolling update of the given ReplicationController.",
 		Long:    rollingupdate_long,
 		Example: rollingupdate_example,
diff --git a/pkg/kubectl/cmd/run.go b/pkg/kubectl/cmd/run.go
index 04f47317999eb..ded53f099a5e2 100644
--- a/pkg/kubectl/cmd/run.go
+++ b/pkg/kubectl/cmd/run.go
@@ -44,7 +44,7 @@ $ kubectl run-container nginx --image=dockerfile/nginx --overrides='{ "apiVersio
 
 func (f *Factory) NewCmdRunContainer(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:     "run-container <name> --image=<image> [--port=<port>] [--replicas=replicas] [--dry-run=<bool>] [--overrides=<inline-json>]",
+		Use:     "run-container NAME --image=image [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]",
 		Short:   "Run a particular image on the cluster.",
 		Long:    run_long,
 		Example: run_example,
@@ -66,7 +66,7 @@ func (f *Factory) NewCmdRunContainer(out io.Writer) *cobra.Command {
 
 func RunRunContainer(f *Factory, out io.Writer, cmd *cobra.Command, args []string) error {
 	if len(args) != 1 {
-		return util.UsageError(cmd, "<name> is required for run-container")
+		return util.UsageError(cmd, "NAME is required for run-container")
 	}
 
 	namespace, err := f.DefaultNamespace(cmd)
diff --git a/pkg/kubectl/cmd/stop.go b/pkg/kubectl/cmd/stop.go
index 72959f865bc7d..e9d397dbbdc21 100644
--- a/pkg/kubectl/cmd/stop.go
+++ b/pkg/kubectl/cmd/stop.go
@@ -49,7 +49,7 @@ func (f *Factory) NewCmdStop(out io.Writer) *cobra.Command {
 		Filenames util.StringList
 	}{}
 	cmd := &cobra.Command{
-		Use:     "stop (-f filename | <resource> (<id> | -l <label> | --all))",
+		Use:     "stop (-f FILENAME | RESOURCE (ID | -l label | --all))",
 		Short:   "Gracefully shut down a resource by id or filename.",
 		Long:    stop_long,
 		Example: stop_example,
diff --git a/pkg/kubectl/cmd/update.go b/pkg/kubectl/cmd/update.go
index d7a1ca03ff5e4..09af529f06c1f 100644
--- a/pkg/kubectl/cmd/update.go
+++ b/pkg/kubectl/cmd/update.go
@@ -43,7 +43,7 @@ $ kubectl update pods my-pod --patch='{ "apiVersion": "v1beta1", "desiredState":
 func (f *Factory) NewCmdUpdate(out io.Writer) *cobra.Command {
 	var filenames util.StringList
 	cmd := &cobra.Command{
-		Use:     "update -f filename",
+		Use:     "update -f FILENAME",
 		Short:   "Update a resource by filename or stdin.",
 		Long:    update_long,
 		Example: update_example,