diff --git a/docs/kustomization.yaml b/docs/kustomization.yaml
index 778130c8c..377d7837c 100644
--- a/docs/kustomization.yaml
+++ b/docs/kustomization.yaml
@@ -212,11 +212,13 @@ crds:
 - crds/typeA.yaml
 - crds/typeB.yaml
 
-# Vars are used to insert values from resources that cannot be referenced
-# otherwise. For example if you need to pass a Service's name to the arguments
-# or environment variables of a program but without hard coding the actual name
-# of the Service you'd insert `$(MY_SERVICE_NAME)` into the value field of the
-# env var or into the command or args of the container as shown here:
+# Vars are used to capture text from one resource's field
+# and insert that text elsewhere.
+#
+# For example, suppose one specify the name of a k8s Service
+# object in a container's command line, and the name of a
+# k8s Secret object in a container's environment variable,
+# so that the following would work:
 # ```
 #   containers:
 #     - image: myimage
@@ -226,19 +228,8 @@ crds:
 #           value: $(SOME_SECRET_NAME)
 # ```
 #
-# Then you'll add an entry to `vars:` like shown below with the same name
-# and a reference to the resource from which to pull the field's value.
-# The actual field's path is optional and by default it will use
-# `metadata.name`. Currently only string type fields are supported, no integers
-# or booleans, etc. Also array access is currently not possible. For example getting
-# the image field of container number 2 inside of a pod can currently not be done.
+# To do so, add an entry to `vars:` as follows:
 #
-# Not every location of a variable is supported. To see a complete list of locations
-# see the file [varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/varreference.go#L20).
-#
-# An example of a situation where you'd not use vars is when you'd like to set a
-# pod's `serviceAccountName`. In that case you would just reference the ServiceAccount
-# by name and Kustomize will resolve it to the eventual name while building the manifests.
 vars:
   - name: SOME_SECRET_NAME
     objref:
@@ -259,6 +250,34 @@ vars:
       apiVersion: apps/v1
     fieldref:
       fieldpath: spec.template.spec.restartPolicy
+#
+# A var is a tuple of variable name, object reference and field
+# reference within that object.  That's where the text is found.
+#
+# The field reference is optional; it defaults to `metadata.name`,
+# a normal default, since kustomize is used to generates or
+# modify the names of resources.
+#
+# At time of writing, only string type fields are supported.
+# No ints, bools, arrays etc.  It's not possible to, say,
+# extract the name of the image in container number 2 of
+# some pod template.
+#
+# A variable reference, i.e. the string '$(FOO)', can only
+# be placed in particular fields of particular objects as
+# specified by kustomize's configuration data.
+#
+# The default config data for vars is at
+# https://github.com/kubernetes-sigs/kustomize/blob/master/pkg/transformers/config/defaultconfig/varreference.go
+# Long story short, the default targets are all
+# container command args and env value fields.
+#
+# Vars should _not_ be used for inserting names in places
+# where kustomize is already handling that job.  E.g.,
+# a Deployment may reference a ConfigMap by name, and
+# if kustomize changes the name of a ConfigMap, it knows
+# to change the name reference in the Deployment.
+
 
 # Images modify the name, tags and/or digest for images without creating patches.
 # E.g. Given this kubernetes Deployment fragment: