diff --git a/examples/transformerconfigs/README.md b/examples/transformerconfigs/README.md
index 6b3d8b56db4..a4cfe5a33c5 100644
--- a/examples/transformerconfigs/README.md
+++ b/examples/transformerconfigs/README.md
@@ -606,3 +606,63 @@ metadata:
     foo.k8s.io/bar: baz
 ```
 Kustomize supports escaping special characters in path, e.g `metadata/annotations/foo.k8s.io\/bar`
+
+## Namespace
+
+The namespace transformer is used to update namespace references in your manifests when you set the `namespace` declaration in your `kustomization.yaml`.
+
+### Example
+
+kustomization.yaml
+
+```
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: example
+
+resources:
+- resources.yaml
+
+configurations:
+  - namespace.yaml
+```
+
+namespace.yaml
+
+
+```
+namespace:
+  - kind: AnimalPark
+    path: spec/gorillaRef/namespace
+    create: true
+```
+
+resources.yaml
+
+```
+apiVersion: animal/v1
+kind: AnimalPark
+metadata:
+  name: ap
+spec:
+  gorillaRef:
+    name: gg
+    kind: Gorilla
+    apiVersion: animal/v1
+```
+
+Output of `kustomize build`:
+
+```
+apiVersion: animal/v1
+kind: AnimalPark
+metadata:
+  name: ap
+  namespace: example
+spec:
+  gorillaRef:
+    apiVersion: animal/v1
+    kind: Gorilla
+    name: gg
+    namespace: example
+```