diff --git a/docs/kustomization.yaml b/docs/kustomization.yaml
index 54e27f297..778130c8c 100644
--- a/docs/kustomization.yaml
+++ b/docs/kustomization.yaml
@@ -260,6 +260,40 @@ vars:
     fieldref:
       fieldpath: spec.template.spec.restartPolicy
 
+# Images modify the name, tags and/or digest for images without creating patches.
+# E.g. Given this kubernetes Deployment fragment:
+# ```
+#  containers:
+#    - name: mypostgresdb
+#      image: postgres:8
+#    - name: nginxapp
+#      image: nginx:1.7.9
+#    - name: myapp
+#      image: my-demo-app:latest
+#    - name: alpine-app
+#      image: alpine:3.7
+#```
+# one can change the `image` in the following ways:
+# 
+# - `postgres:8` to `my-registry/my-postgres:v1`,
+# - nginx tag `1.7.9` to `1.8.0`,
+# - image name `my-demo-app` to `my-app`,
+# - alpine's tag `3.7` to a digest value
+#
+# all with the following *kustomization*:
+
+images:
+  - name: postgres
+    newName: my-registry/my-postgres
+    newTag: v1
+  - name: nginx
+    newTag: 1.8.0
+  - name: my-demo-app
+    newName: my-app
+  - name: alpine
+    digest: sha256:24a0c4b4a4c0eb97a1aabb8e29f18e917d05abfe1b7a7c07857230879ce7d3d3
+
+# ImageTags is deprecated, instead use Image.
 # ImageTags modify the tags for images without creating patches.
 # E.g. Given this fragment of a Deployment:
 # ```
diff --git a/examples/README.md b/examples/README.md
index eb259837b..5b94edadb 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -37,7 +37,7 @@ go get sigs.k8s.io/kustomize
    
  * [vars](wordpress/README.md) - Injecting k8s runtime data into container arguments (e.g. to point wordpress to a SQL service) by vars.
  
- * [image tags](imageTags.md) - Updating image tags without applying a patch.
+ * [image names and tags](image.md) - Updating image names and tags without applying a patch.
 
  * [multibases](multibases/README.md) - Composing three variants (dev, staging, production) with a common base.
 
diff --git a/examples/imageTags.md b/examples/image.md
similarity index 66%
rename from examples/imageTags.md
rename to examples/image.md
index d6a5fe11a..a6248c1f3 100644
--- a/examples/imageTags.md
+++ b/examples/image.md
@@ -1,4 +1,4 @@
-# Demo: change image tags
+# Demo: change image names and tags
 
 
 Define a place to work:
@@ -42,21 +42,22 @@ EOF
 ```
 
 The `myapp-pod` resource declares an initContainer and a container, both use the image `busybox:1.29.0`.
-The tag `1.29.0` can be changed by adding `imageTags` in `kustomization.yaml`.
+The image `busybox` and tag `1.29.0` can be changed by adding `images` in `kustomization.yaml`.
 
 
-Add `imageTags`:
-<!-- @addImageTags @test -->
+Add `images`:
+<!-- @addImages @test -->
 ```
 cd $DEMO_HOME
-kustomize edit set imagetag busybox:1.29.1
+kustomize edit set image busybox=alpine:3.6
 ```
 
-The `kustomization.yaml` will be added following `imageTags`.
+The folowing `images` will be added to `kustomization.yaml`:
 > ```
-> imageTags:
+> images:
 > - name: busybox
->   newTag: 1.29.1
+>   newName: alpine
+>   newTag: 3.6
 > ```
 
 Now build this `kustomization`
@@ -65,11 +66,11 @@ Now build this `kustomization`
 kustomize build $DEMO_HOME
 ```
 
-Confirm that this replaces _both_ busybox tags:
+Confirm that this replaces _both_ busybox images and tags for `alpine:3.6`:
 
-<!-- @confirmTags @test -->
+<!-- @confirmImages @test -->
 ```
-test 2 == \
-  $(kustomize build $DEMO_HOME | grep busybox:1.29.1 | wc -l); \
+test 2 = \
+  $(kustomize build $DEMO_HOME | grep alpine:3.6 | wc -l); \
   echo $?
 ```