docs(*): refresh docs

This refreshes docs, as discussed in #719, and adds a few new sections
to the docs.

Closes #719

README.md

@@ -50,8 +50,11 @@ including installing pre-releases.
 - [Installing Helm](docs/install.md)
 - [Using Helm](docs/using_helm.md)
 - [Developing Charts](docs/charts.md)
+	- [Chart Lifecycle Hooks](docs/chart_hooks.md)
+	- [Chart Tips and Tricks](docs/chart_tips_and_tricks.md)
 	- [Chart Repository Guide](docs/chart_repository.md)
 	- [Syncing your Chart Repository](docs/chart_repository_sync_example.md)
+	- [Signing Charts](docs/provenance.md)
 - [Architecture](docs/architecture.md)
 - [Developers](docs/developers.md)
 - [History](docs/history.md)

docs/architecture.md

@@ -11,7 +11,7 @@ can do the following:
 - Package charts into chart archive (tgz) files
 - Interact with chart repositories where charts are stored
 - Install and uninstall charts into an existing Kubernetes cluster
-- Manage the releases of charts that have been installed with Helm
+- Manage the release cycle of charts that have been installed with Helm
 
 For Helm, there are three important concepts:
 
@@ -22,9 +22,6 @@ For Helm, there are three important concepts:
 3. A _release_ is a running instance of a _chart_, combined with a
    specific _config_.
 
-Following the formula made famous by the [12 Factor App](http://12factor.net/), _chart + config
-= release_.
-
 ## Components
 
 Helm has two major components:
@@ -64,20 +61,4 @@ communicate with Kubernetes. Currently, that library uses REST+JSON.
 The Tiller server stores information in ConfigMaps located inside of
 Kubernetes. It does not need its own database.
 
-### Structure of the Code
-
-The individual programs are located in `cmd/`. Shared libraries are
-stored in `pkg/`. The raw ProtoBuf files are stored in `_proto/hapi`
-(where `hapi` stands for the Helm Application Programming Interface).
-The Go files generated from the `proto` definitions are stored in
-`pkg/proto`.
-
-Docker images are built by cross-compiling Linux binaries and then
-building a Docker image from the files in `rootfs`.
-
-The `scripts/` directory contains a number of utility scripts. Most of these
-are used by the CI/CD pipeline.
-
-Go dependencies are managed with
-[Glide](https://github.com/Masterminds/glide) and stored in the
-`vendor/` directory.
+Configuration files are, when possible, written in YAML.

docs/charts.md

@@ -32,7 +32,8 @@ wordpress/
   templates/NOTES.txt # OPTIONAL: A plain text file containing short usage notes
 ```
 
-Helm will silently strip out any other files.
+Helm reserves use of the `charts/` and `templates/` directories, and of
+the listed file names. Other files will be left as they are.
 
 ## The Chart.yaml File
 
@@ -204,16 +205,18 @@ team.
 
 ## Templates and Values
 
-By default, Helm Chart templates are written in the Go template language, with the
-addition of 50 or so [add-on template
-functions](https://github.com/Masterminds/sprig). (In the future, Helm
-may support other template languages, like Python Jinja.)
+Helm Chart templates are written in the
+[Go template language](https://golang.org/pkg/text/template/), with the
+addition of 50 or so add-on template
+functions [from the Sprig library](https://github.com/Masterminds/sprig) and a
+few other [specialized functions](charts_tips_and_tricks.md).
 
 All template files are stored in a chart's `templates/` folder. When
 Helm renders the charts, it will pass every file in that directory
 through the template engine.
 
 Values for the templates are supplied two ways:
+
   - Chart developers may supply a file called `values.yaml` inside of a
     chart. This file can contain default values.
   - Chart users may supply a YAML file that contains values. This can be
@@ -221,6 +224,7 @@ Values for the templates are supplied two ways:
 
 When a user supplies custom values, these values will override the
 values in the chart's `values.yaml` file.
+
 ### Template Files
 
 Template files follow the standard conventions for writing Go templates
@@ -269,6 +273,9 @@ It can use the following four template values (usually defined in a
 All of these values are defined by the template author. Helm does not
 require or dictate parameters.
 
+To see many working charts, check out the [Kubernetes Charts
+project](https://github.com/kubernetes/charts)
+
 ### Predefined Values
 
 Values that are supplied via a `values.yaml` file (or via the `--set`
@@ -296,7 +303,8 @@ sensitive_.
 
 **NOTE:** Any unknown Chart.yaml fields will be dropped. They will not
 be accessible inside of the `Chart` object. Thus, Chart.yaml cannot be
-used to pass arbitrarily structured data into the template.
+used to pass arbitrarily structured data into the template. The values
+file can be used for that, though.
 
 ### Values files
 
@@ -342,6 +350,9 @@ Note that only the last field was overridden.
 `values.yaml`. But files specified on the command line can be named
 anything.
 
+**NOTE:** If the `--set` flag is used on `helm install` or `helm upgrade`, those
+values are simply converted to YAML on the client side.
+
 Any of these values are then accessible inside of templates using the
 `.Values` object:
 
@@ -479,157 +490,7 @@ standard references that will help you out.
 
 - [Go templates](https://godoc.org/text/template)
 - [Extra template functions](https://godoc.org/github.com/Masterminds/sprig)
-- [The YAML format]()
-
-## Hooks
-
-Helm provides a _hook_ mechanism to allow chart developers to intervene
-at certain points in a release's life cycle. For example, you can use
-hooks to:
-
-- Load a ConfigMap or Secret during install before any other charts are
-  loaded.
-- Execute a Job to backup up a database before installing a new chart,
-  and then execute a second job after the upgrade in order to restore
-  data.
-- Run a Job before deleting a release to gracefully take a service out
-  of rotation before removing it.
-
-Hooks work like regular templates, but they have special annotations
-that cause Helm to utilize them differently. In this section, we cover
-the basic usage pattern for hooks.
-
-### The Available Hooks
-
-The following hooks are defined:
-
-- pre-install: Executes after templates are rendered, but before any
-  resources are created in Kubernetes.
-- post-install: Executes after all resources are loaded into Kubernetes
-- pre-delete: Executes on a deletion request before any resources are
-  deleted from Kubernetes.
-- post-delete: Executes on a deletion request after all of the release's
-  resources have been deleted.
-- pre-upgrade: Executes on an upgrade request after templates are
-  rendered, but before any resources are loaded into Kubernetes (e.g.
-  before a kuberntes apply operation).
-- post-upgrade: Executes on an upgrade after all resources have been
-  upgraded.
-
-### Hooks and the Release Lifecycle
-
-Hooks allow you, the chart developer, an opportunity to perform
-operations at strategic points in a release lifecycle. For example,
-consider the lifecycle for a `helm install`. By default, the lifecycle
-looks like this:
-
-1. User runs `helm install foo`
-2. Chart is loaded into Tiller
-3. After some verification, Tiller renders the `foo` templates
-4. Tiller loads the resulting resources into Kubernetes
-5. Tiller returns the release name (and other data) to the client
-6. The client exits
-
-Helm defines two hooks for the `install` lifecycle: `pre-install` and
-`post-install`. If the developer of the `foo` chart implements both
-hooks, the lifecycle is altered like this:
-
-1. User runs `helm install foo`
-2. Chart is loaded into Tiller
-3. After some verification, Tiller renders the `foo` templates
-4. Tiller executes the `pre-install` hook (loading hook resources into
-   Kubernetes)
-5. Tiller waits until the hook is "Ready"
-6. Tiller loads the resulting resources into Kubernetes
-7. Tiller executes the `post-install` hook (loading hook resources)
-8. Tiller waits until the hook is "Ready"
-9. Tiller returns the release name (and other data) to the client
-10. The client exits
-
-What does it mean to wait until a hook is ready? This depends on the
-resource declared in the hook. If the resources is a `Job` kind, Tiller
-will wait until the job successfully runs to completion. And if the job
-fails, the release will fail. This is a _blocking operation_, so the
-Helm client will pause while the Job is run.
-
-For all other kinds, as soon as Kubernetes marks the resource as loaded
-(added or updated), the resource is considered "Ready". When many
-resources are declared in a hook, the resources are executed serially,
-but the order of their execution is not guaranteed.
-
-#### Hook resources are unmanaged
-
-The resources that a hook creates are not tracked or managed as part of the
-release. Once Tiller verifies that the hook has reached its ready state, it
-will leave the hook resource alone.
-
-Practically speaking, this means that if you create resources in a hook, you
-cannot rely upon `helm delete` to remove the resources. To destroy such
-resources, you need to write code to perform this operation in a `pre-delete`
-or `post-delete` hook.
-
-### Writing a Hook
-
-Hooks are just Kubernetes manfiest files with special annotations in the
-`metadata` section. Because they are template files, you can use all of
-the normal template features, including reading `.Values`, `.Release`,
-and `.Template`.
-
-For example, this template, stored in `templates/post-install-job.yaml`,
-declares a job to be run on `post-install`:
-
-```yaml
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: "{{.Release.Name}}"
-  labels:
-    heritage: {{.Release.Service | quote }}
-    release: {{.Release.Name | quote }}
-    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
-  annotations:
-    # This is what defines this resource as a hook. Without this line, the
-    # job is considered part of the release.
-    "helm.sh/hook": post-install
-spec:
-  template:
-    metadata:
-      name: "{{.Release.Name}}"
-      labels:
-        heritage: {{.Release.Service | quote }}
-        release: {{.Release.Name | quote }}
-        chart: "{{.Chart.Name}}-{{.Chart.Version}}"
-    spec:
-      restartPolicy: Never
-      containers:
-      - name: post-install-job
-        image: "alpine:3.3"
-        command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]
-
-```
-
-What makes this template a hook is the annotation:
-
-```
-  annotations:
-    "helm.sh/hook": post-install
-```
-
-One resource can implement multiple hooks:
-
-```
-  annotations:
-    "helm.sh/hook": post-install,post-upgrade
-```
-
-Similarly, there is no limit to the number of different resources that
-may implement a given hook. For example, one could declare both a secret
-as a config map as a pre-install hook. It is important to keep in mind,
-though, that there are no ordering guarantees about hooks.
-
-When subcharts declare hooks, those are also evaluated. There is no way
-for a top-level chart to disable the hooks declared by subcharts. And
-again, there is no guaranteed ordering.
+- [The YAML format](http://yaml.org/spec/)
 
 ## Using Helm to Manage Charts
 

docs/charts_hooks.md

+# Hooks
+
+Helm provides a _hook_ mechanism to allow chart developers to intervene
+at certain points in a release's life cycle. For example, you can use
+hooks to:
+
+- Load a ConfigMap or Secret during install before any other charts are
+  loaded.
+- Execute a Job to backup up a database before installing a new chart,
+  and then execute a second job after the upgrade in order to restore
+  data.
+- Run a Job before deleting a release to gracefully take a service out
+  of rotation before removing it.
+
+Hooks work like regular templates, but they have special annotations
+that cause Helm to utilize them differently. In this section, we cover
+the basic usage pattern for hooks.
+
+## The Available Hooks
+
+The following hooks are defined:
+
+- pre-install: Executes after templates are rendered, but before any
+  resources are created in Kubernetes.
+- post-install: Executes after all resources are loaded into Kubernetes
+- pre-delete: Executes on a deletion request before any resources are
+  deleted from Kubernetes.
+- post-delete: Executes on a deletion request after all of the release's
+  resources have been deleted.
+- pre-upgrade: Executes on an upgrade request after templates are
+  rendered, but before any resources are loaded into Kubernetes (e.g.
+  before a kuberntes apply operation).
+- post-upgrade: Executes on an upgrade after all resources have been
+  upgraded.
+
+## Hooks and the Release Lifecycle
+
+Hooks allow you, the chart developer, an opportunity to perform
+operations at strategic points in a release lifecycle. For example,
+consider the lifecycle for a `helm install`. By default, the lifecycle
+looks like this:
+
+1. User runs `helm install foo`
+2. Chart is loaded into Tiller
+3. After some verification, Tiller renders the `foo` templates
+4. Tiller loads the resulting resources into Kubernetes
+5. Tiller returns the release name (and other data) to the client
+6. The client exits
+
+Helm defines two hooks for the `install` lifecycle: `pre-install` and
+`post-install`. If the developer of the `foo` chart implements both
+hooks, the lifecycle is altered like this:
+
+1. User runs `helm install foo`
+2. Chart is loaded into Tiller
+3. After some verification, Tiller renders the `foo` templates
+4. Tiller executes the `pre-install` hook (loading hook resources into
+   Kubernetes)
+5. Tiller waits until the hook is "Ready"
+6. Tiller loads the resulting resources into Kubernetes
+7. Tiller executes the `post-install` hook (loading hook resources)
+8. Tiller waits until the hook is "Ready"
+9. Tiller returns the release name (and other data) to the client
+10. The client exits
+
+What does it mean to wait until a hook is ready? This depends on the
+resource declared in the hook. If the resources is a `Job` kind, Tiller
+will wait until the job successfully runs to completion. And if the job
+fails, the release will fail. This is a _blocking operation_, so the
+Helm client will pause while the Job is run.
+
+For all other kinds, as soon as Kubernetes marks the resource as loaded
+(added or updated), the resource is considered "Ready". When many
+resources are declared in a hook, the resources are executed serially,
+but the order of their execution is not guaranteed.
+
+### Hook resources are unmanaged
+
+The resources that a hook creates are not tracked or managed as part of the
+release. Once Tiller verifies that the hook has reached its ready state, it
+will leave the hook resource alone.
+
+Practically speaking, this means that if you create resources in a hook, you
+cannot rely upon `helm delete` to remove the resources. To destroy such
+resources, you need to write code to perform this operation in a `pre-delete`
+or `post-delete` hook.
+
+## Writing a Hook
+
+Hooks are just Kubernetes manfiest files with special annotations in the
+`metadata` section. Because they are template files, you can use all of
+the normal template features, including reading `.Values`, `.Release`,
+and `.Template`.
+
+For example, this template, stored in `templates/post-install-job.yaml`,
+declares a job to be run on `post-install`:
+
+```yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: "{{.Release.Name}}"
+  labels:
+    heritage: {{.Release.Service | quote }}
+    release: {{.Release.Name | quote }}
+    chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+  annotations:
+    # This is what defines this resource as a hook. Without this line, the
+    # job is considered part of the release.
+    "helm.sh/hook": post-install
+spec:
+  template:
+    metadata:
+      name: "{{.Release.Name}}"
+      labels:
+        heritage: {{.Release.Service | quote }}
+        release: {{.Release.Name | quote }}
+        chart: "{{.Chart.Name}}-{{.Chart.Version}}"
+    spec:
+      restartPolicy: Never
+      containers:
+      - name: post-install-job
+        image: "alpine:3.3"
+        command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]
+
+```
+
+What makes this template a hook is the annotation:
+
+```
+  annotations:
+    "helm.sh/hook": post-install
+```
+
+One resource can implement multiple hooks:
+
+```
+  annotations:
+    "helm.sh/hook": post-install,post-upgrade
+```
+
+Similarly, there is no limit to the number of different resources that
+may implement a given hook. For example, one could declare both a secret
+as a config map as a pre-install hook. It is important to keep in mind,
+though, that there are no ordering guarantees about hooks.
+
+When subcharts declare hooks, those are also evaluated. There is no way
+for a top-level chart to disable the hooks declared by subcharts. And
+again, there is no guaranteed ordering.
+

docs/charts_tips_and_tricks.md

+# Chart Development Tips and Tricks
+
+This guide covers some of the tips and tricks Helm chart developers have
+learned while building production-quality charts.
+
+## Quote Strings, Don't Quote Integers
+
+When you are working with string data, you are always safer quoting the
+strings than leaving them as bare words:
+
+```
+name: {{.Values.MyName | quote }}
+```
+
+But when working with integers _do not quote the values._ That can, in
+many cases, cause parsing errors inside of Kubernetes.
+
+```
+port: {{ .Values.Port }}
+```
+
+## Using the 'include' Function
+
+Go provides a way of including one template in another using a built-in
+`template` directive. However, the built-in function cannot be used in
+Go template pipelines.
+
+To make it possible to include a template, and then perform an operation
+on that template's output, Helm has a special `include` function:
+
+```
+{{ include "toYaml" $value | indent 2 }}
+```
+
+The above includes a template called `toYaml`, passes it `$value`, and
+then passes the output of that template to the `indent` function.
+
+Because YAML ascribes significance to indentation levels and whitespace,
+this is one great way to include snippets of code, but handle
+indentation in a relevant context.
+
+## Using "Partials" and Template Includes
+
+Sometimes you want to create some reusable parts in your chart, whether
+they're blocks or template partials. And often, it's cleaner to keep
+these in their own files.
+
+In the `templates/` directory, any file that begins with an
+underscore(`_`) is not expected to ouput a Kubernetes manifest file. So
+by convention, helper templates and partials are placed in a
+`_helpers.tpl` file.
+
+## YAML is a Superset of JSON
+
+According to the YAML specification, YAML is a superset of JSON. That
+means that any valid JSON structure ought to be valid in YAML.
+
+This has an advantage: Sometimes template developers may find it easier
+to express a datastructure with a JSON-like syntax rather than deal with
+YAML's whitespace sensitivity.
+
+As a best practice, templates should follow a YAML-like syntax _unless_
+the JSON syntax substantially reduces the risk of a formatting issue.
+
+## Be Careful with Generating Random Values
+
+There are functions in Helm that allow you to generate random data,
+cryptographic keys, and so on. These are fine to use. But be aware that
+during upgrades, templates are re-executed. When a template run
+generates data that differs from the last run, that will trigger an
+update of that resource.

docs/developers.md

@@ -104,6 +104,25 @@ Make sure you have read and understood the main CONTRIBUTING guide:
 
 https://github.com/kubernetes/helm/blob/master/CONTRIBUTING.md
 
+### Structure of the Code
+
+The code for the Helm project is organized as follows:
+
+- The individual programs are located in `cmd/`. Code inside of `cmd/`
+  is not designed for library re-use.
+- Shared libraries are stored in `pkg/`.
+- The raw ProtoBuf files are stored in `_proto/hapi` (where `hapi` stands for 
+  the Helm Application Programming Interface).
+- The Go files generated from the `proto` definitions are stored in `pkg/proto`.
+- The `scripts/` directory contains a number of utility scripts. Most of these
+  are used by the CI/CD pipeline.
+- The `rootfs/` folder is used for Docker-specific files.
+- The `docs/` folder is used for documentation and examples.
+
+Go dependencies are managed with
+[Glide](https://github.com/Masterminds/glide) and stored in the
+`vendor/` directory.
+
 ### Git Conventions
 
 We use Git for our version control system. The `master` branch is the
@@ -145,7 +164,7 @@ Common scopes:
 - tiller: The Tiller server
 - proto: Protobuf definitions
 - pkg/lint: The lint package. Follow a similar convention for any
-  package,
+  package
 - `*`: two or more scopes
 
 Read more:
@@ -159,7 +178,7 @@ We follow the Go coding style standards very closely. Typically, running
 `go fmt` will make your code beautiful for you.
 
 We also typically follow the conventions recommended by `go lint` and
-`govet`. Run `make test-style` to test the style conformance.
+`gometalinter`. Run `make test-style` to test the style conformance.
 
 Read more:
 

docs/history.md

@@ -3,7 +3,7 @@
 Kubernetes Helm is the merged result of [Helm
 Classic](https://github.com/helm/helm) and the Kubernetes port of GCS Deployment
 Manager. The project was jointly started by Google and Deis, though it
-is now part of the CNCF.
+is now part of the CNCF. Many companies now contribute regularly to Helm.
 
 Differences from Helm Classic:
 
@@ -18,7 +18,7 @@ Differences from Helm Classic:
     or `template` commands.
   - Helm makes it easy to configure your releases -- and share the
     configuration with the rest of your team.
-- Helm chart repositories now use plain HTTP instead of Git/GitHub.
+- Helm chart repositories now use plain HTTP(S) instead of Git/GitHub.
   There is no longer any GitHub dependency.
   - A chart server is a simple HTTP server
   - Charts are referenced by version

docs/install.md

@@ -9,7 +9,7 @@ proceeds to show two ways to install the server.
 The Helm client can be installed either from source, or from pre-built binary
 releases.
 
-### From the GitHub Releases
+### From the Binary Releases
 
 Every [release](https://github.com/kubernetes/helm/releases) of Helm
 provides binary releases for a variety of OSes. These binary versions
@@ -53,7 +53,8 @@ Here are links to the common builds:
 Building Helm from source is slightly more work, but is the best way to
 go if you want to test the latest (pre-release) Helm version.
 
-You must have a working Go environment with [glide](https://github.com/Masterminds/glide) and Mercurial installed.
+You must have a working Go environment with
+[glide](https://github.com/Masterminds/glide) and Mercurial installed.
 
 ```console
 $ cd $GOPATH
@@ -88,6 +89,12 @@ view`). Once it connects, it will install `tiller` into the
 After `helm init`, you should be able to run `kubectl get po --namespace
 kube-system` and see Tiller running.
 
+You can explicitly tell `helm init` to...
+
+- Install the canary build with the `--canary-image` flag
+- Install a particular image (version) with `--tiller-image`
+- Install to a particular cluster with `--kube-context`
+
 Once Tiller is installed, running `helm version` should show you both
 the client and server version. (If it shows only the client version,
 `helm` cannot yet connect to the server. Use `kubectl` to see if any
@@ -99,10 +106,10 @@ Canary images are built from the `master` branch. They may not be
 stable, but they offer you the chance to test out the latest features.
 
 The easiest way to install a canary image is to use `helm init` with the
-`--tiller-image` flag:
+`--canary-image` flag:
 
 ```console
-$ helm init -i "gcr.io/kubernetes-helm/tiller:canary"
+$ helm init --canary-image
 ```
 
 This will use the most recently built container image. You can always
@@ -142,6 +149,13 @@ Server: &version.Version{SemVer:"v2.0.0-alpha.4", GitCommit:"a5...", GitTreeStat
 Importantly, even when running locally, Tiller will store release
 configuration in ConfigMaps inside of Kubernetes.
 
+## Deleting or Reinstalling Tiller
+
+Because Tiller stores its data in Kubernetes ConfigMaps, you can safely
+delete and re-install Tiller without worrying about losing any data. The
+recommended way of deleting Tiller is with `kubectl delete deployment
+tiller-deployment -n kube-system`
+
 ## Conclusion
 
 In most cases, installation is as simple as getting a pre-built `helm` binary

docs/quickstart.md

@@ -4,22 +4,29 @@ This guide covers how you can quickly get started using Helm.
 
 ## Prerequisites
 
-- You must have Kubernetes installed, and have a local configured copy
-  of `kubectl`.
+- You must have Kubernetes installed. We recommend version 1.4.1 or
+  later.
+- You should also have a local configured copy of `kubectl`.
 
 Helm will figure out where to install Tiller by reading your Kubernetes
 configuration file (usually `$HOME/.kube/config`). This is the same file
-that `kubectl` uses, so to find out which cluster Tiller would install
-to, you can run `kubectl cluster-info`.
+that `kubectl` uses.
+
+To find out which cluster Tiller would install to, you can run
+`kubectl config current-context` or `kubectl cluster-info`.
+
+```console
+$ kubectl config current-context
+my-cluster
+```
 
 ## Install Helm
 
-Download a binary release of the Helm client from 
-[the official project page](https://github.com/kubernetes/helm/releases).
+Download a binary release of the Helm client. You can use tools like
+`homebrew`, or look at [the official releases page](https://github.com/kubernetes/helm/releases).
 
-Alternately, you can clone the GitHub project and build your own
-client from source. The quickest route to installing from source is to
-run `make bootstrap build`, and then use `bin/helm`.
+For more details, or for other options, see [the installation
+guide](install.md).
 
 ## Initialize Helm and Install Tiller
 
@@ -30,47 +37,47 @@ install Tiller into your Kubernetes cluster in one step:
 $ helm init
 ```
 
-## Install an Example Chart
+This will install Tiller into the Kubernetes cluster you saw with
+`kubectl config current-context`.
+
+**TIP:** Want to install into a different cluster? Use the
+`--kube-context` flag.
 
-To install a chart, you can run the `helm install` command.
-Let's use an example chart from this repository.
-Make sure you are in the root directory of this repo.
+## Install an Example Chart
 
+To install a chart, you can run the `helm install` command. Helm has
+several ways to find and install a chart, but the easiest is to use one
+of the official `stable` charts.
 
 ```console
+$ helm repo update              # Make sure we get the latest list of charts
 $ helm install stable/mysql
 Released smiling-penguin
 ```
 
 In the example above, the `stable/mysql` chart was released, and the name of
-our new release is `smiling-penguin`. You get a simple idea of this
-MySQL chart by running `helm inspect stable/mysql`.
+our new release is `smiling-penguin`. You get a simple idea of the
+features of this MySQL chart by running `helm inspect stable/mysql`.
 
-## Change a Default Chart Value
+Whenever you install a chart, a new release is created. So one chart can
+be installed multiple times into the same cluster. And each can be
+independently managed and upgrade.
 
-A nice feature of helm is the ability to change certain values of the package for the install.
-Let's install the `nginx` example from this repository but change the `replicaCount` to 7.
+The `helm install` command is a very powerful command with many
+capabilities. To learn more about it, check out the [Using Helm
+Guide](using_helm.md)
 
-```console
-$ helm install --set replicaCount=7 ./docs/examples/nginx
-happy-panda
-```
-
-You can view the chart for this example in 
-[docs/examples/nginx/Chart.yaml](examples/nginx/Chart.yaml) and the default values in
-[docs/examples/nginx/values.yaml](examples/nginx/values.yaml).
+## Learn About Releases
 
-## Learn About The Release
-
-To find out about our release, run `helm status`:
+It's easy to see what has been released using Helm:
 
 ```console
-$ helm status smiling-penguin
-Status: DEPLOYED
+$ helm ls
+NAME           	VERSION	 UPDATED                       	STATUS         	CHART
+smiling-penguin	 1      	Wed Sep 28 12:59:46 2016      	DEPLOYED       	mysql-0.1.0
 ```
 
-The `status` command will display information about a release in your
-cluster.
+The `helm list` function will show you a list of all deployed releases.
 
 ## Uninstall a Release
 
@@ -87,8 +94,13 @@ still be able to request information about that release:
 ```console
 $ helm status smiling-penguin
 Status: DELETED
+...
 ```
 
+Because Helm tracks your releases even after you've deleted them, you
+can audit a cluster's history, and even undelete a release (with `helm
+rollback`).
+
 ## Reading the Help Text
 
 To learn more about the available Helm commands, use `helm help` or type

docs/using_helm.md

@@ -13,8 +13,8 @@ covers the particulars of Helm commands, and explains how to use Helm.
 
 A *Chart* is a Helm package. It contains all of the resource definitions
 necessary to run an application, tool, or service inside of a Kubernetes
-cluster. Think of it like a Homebrew formula or an `apt` or `rpm`
-package for Kubernetes.
+cluster. Think of it like the Kubernetes equivalent of a Homebrew formula,
+an Apt dpkg, or a Yum RPM file.
 
 A *Repository* is the place where charts can be collected and shared.
 It's like Perl's [CPAN archive](http://www.cpan.org) or the
@@ -45,9 +45,11 @@ You can see which charts are available by running `helm search`:
 
 ```
 $ helm search
-stable/drupal
-stable/jenkins
-stable/mariadb
+NAME                 	VERSION 	DESCRIPTION
+stable/drupal   	0.3.2   	One of the most versatile open source content m...
+stable/jenkins  	0.1.0   	A Jenkins Helm chart for Kubernetes.
+stable/mariadb  	0.5.1   	Chart for MariaDB
+stable/mysql    	0.1.0   	Chart for MySQL
 ...
 ```
 
@@ -56,17 +58,22 @@ can narrow down your results by searching with a filter:
 
 ```
 $ helm search mysql
-stable/mysql
-stable/mariadb
+NAME               	VERSION	DESCRIPTION
+stable/mysql  	0.1.0  	Chart for MySQL
+stable/mariadb	0.5.1  	Chart for MariaDB
 ```
 
-Now you will only see the results that match your filter. Why is
-`mariadb` in the list? Because its package description. We can use `helm
-inspect chart` to see this:
+Now you will only see the results that match your filter. MySQL is
+listed, of course, but so is MariaDB. Why? Because its full description
+relates it to MySQL:
+
+Why is
+`mariadb` in the list? Because its package description relates it to
+MySQL. We can use `helm inspect chart` to see this:
 
 ```
 $ helm inspect stable/mariadb
-Fetched stable/mariadb-0.3.0.tgz to /Users/mattbutcher/Code/Go/src/k8s.io/helm/mariadb-0.3.0.tgz
+Fetched stable/mariadb to mariadb-0.5.1.tgz
 description: Chart for MariaDB
 engine: gotpl
 home: https://mariadb.org
@@ -75,13 +82,7 @@ keywords:
 - mysql
 - database
 - sql
-maintainers:
-- email: containers@bitnami.com
-  name: Bitnami
-name: mariadb
-sources:
-- https://github.com/bitnami/bitnami-docker-mariadb
-version: 0.3.0
+...
 ```
 
 Search is a good way to find available packages. Once you have found a
@@ -223,6 +224,15 @@ $ helm install -f config.yaml stable/mariadb
 The above will set the default MariaDB user to `user0`, but accept all
 the rest of the defaults for that chart.
 
+### More Installation Methods
+
+The `helm install` command can install from several sources:
+
+- A chart repository (as we've seen above)
+- A local chart archive (`helm install foo-0.1.1.tgz`)
+- An unpacked chart directory (`helm install path/to/foo`)
+- A full URL (`helm install https://example.com/charts/foo-1.2.3.tgz`)
+
 ## 'helm upgrade' and 'helm rollback': Upgrading a Release, and Recovering on Failure
 
 When a new version of a chart is released, or when you want to change