From 3fe047f79cc9841d2333221a3d485667c271f2cb Mon Sep 17 00:00:00 2001
From: Jeffrey Regan <jregan@google.com>
Date: Wed, 10 Oct 2018 15:54:37 -0700
Subject: [PATCH] Update ptrs to DAM doc.

---
 docs/eschewedFeatures.md |  5 +++++
 docs/glossary.md         | 25 ++++++++++++++-----------
 2 files changed, 19 insertions(+), 11 deletions(-)

diff --git a/docs/eschewedFeatures.md b/docs/eschewedFeatures.md
index b980ab0d8..4743b3751 100644
--- a/docs/eschewedFeatures.md
+++ b/docs/eschewedFeatures.md
@@ -1,5 +1,9 @@
 # Eschewed Features
 
+For a bigger picture about why kustomize
+does some things and not others, see the
+glossary entry for [DAM].
+
 ## Removal directives
 
 `kustomize` supports configurations that can be reasoned about as
@@ -74,6 +78,7 @@ In this way the resources, patches and bases used at _build time_
 remain explicitly declared in version control.
 
 
+[DAM]: glossary.md#declarative-application-management
 [base]: glossary.md#base
 [kustomization]: glossary.md#kustomization
 [OTS workflow]: workflows.md#off-the-shelf-configuration
diff --git a/docs/glossary.md b/docs/glossary.md
index 3f86fbc58..8a3aaca1a 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -1,6 +1,7 @@
 # Glossary
 
 [DAM]: #declarative-application-management
+[Declarative Application Management]: https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/declarative-application-management.md
 [JSON]: https://www.json.org/
 [JSONPatch]: https://tools.ietf.org/html/rfc6902
 [Resource]: #resource
@@ -98,20 +99,22 @@ periodically capturing someone else's upgrades to the
 
 ## declarative application management
 
-_Declarative Application Management_ (DAM) is a [set of
-ideas](https://goo.gl/T66ZcD) aiming to ease management
-of k8s clusters.
+Kustomize aspires to support [Declarative Application Management],
+a set of best practices around managing k8s clusters.
 
- * Works with any configuration, be it bespoke,
+In brief, kustomize should
+
+ * Work with any configuration, be it bespoke,
    off-the-shelf, stateless, stateful, etc.
- * Supports common customizations, and creation of
-   [variants] (dev vs. staging vs. production).
- * Exposes and teaches native k8s APIs, rather than
-   hiding them.
- * No friction integration with version control to
+ * Support common customizations, and creation of
+   [variants] (e.g. _development_ vs.
+   _staging_ vs. _production_).
+ * Expose and teach native k8s APIs, rather than
+   hide them.
+ * Add no friction to version control integration to
    support reviews and audit trails.
- * Composable with other tools in a unix sense.
- * Eschews crossing the line into templating, domain
+ * Compose with other tools in a unix sense.
+ * Eschew crossing the line into templating, domain
    specific languages, etc., frustrating the other
    goals.