From 5fa209acfab815aeb1d346fce99d60ca25fb87e5 Mon Sep 17 00:00:00 2001
From: Jeffrey Regan <jregan@google.com>
Date: Wed, 22 Aug 2018 12:12:10 -0700
Subject: [PATCH] Tweak docs readme

---
 docs/README.md    | 19 ++++++++++---------
 docs/workflows.md |  7 +++++--
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 8a750dea3..a6f53ed20 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,12 +1,13 @@
 # Kustomize docs
    
- * [glossary](glossary.md) - glossary for Kustomize.
- 
- * [Sample kustomization.yaml](kustomization.yaml) - A sample kustomization.yaml
-   with explanation for each field.
-   
- * [workflow](workflows.md) - Explaining the workflow for
-   both bespoke configuration and off-the-shelf configuration.
+ * [kustomization.yaml](kustomization.yaml) - Example of a
+   [kustomization](glossary.md#kustomization)
+   with explanations of each field.
+
+ * [workflow](workflows.md) - Some steps one might take in using
+   bespoke and off-the-shelf configurations.
   
- * [eschewed features](eschewedFeatures.md) - explaining the eschewed features
-    and why they are not supported in Kustomize.
\ No newline at end of file
+ * [glossary](glossary.md) - An attempt to disambiguiate terminology.
+   
+ * [eschewed features](eschewedFeatures.md) - Why certain features are (currently)
+   not supported in Kustomize.
diff --git a/docs/workflows.md b/docs/workflows.md
index a596e75dc..c1eca62f3 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -21,14 +21,17 @@ use and maintain a configuration.
 
 ## Bespoke configuration
 
-In this workflow, all configuration files are owned by
-the user.  No content is incorporated from version
+In this workflow, all configuration (resource YAML) files
+are owned by the user.  No content is incorporated from version
 control repositories owned by others.
 
 ![bespoke config workflow image][workflowBespoke]
 
 #### 1) create a directory in version control
 
+Speculate some overall cluster application called _ldap_;
+we want to keep its configuration in its own repo.
+
 > ```
 > git init ~/ldap
 > ```