Improve secrets docs.

Explain that imagePullSecrets added to a service account
are added automatically to pods using that service account.

Reword text to not imply that ordinary secrets added to
a service account are not automatically added as volumes
to a pod.

docs/user-guide/secrets.md

@@ -43,11 +43,12 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf
 
 - [Secrets](#secrets)
   - [Overview of Secrets](#overview-of-secrets)
-    - [Service Accounts Automatically Create and Use Secrets with API Credentials](#service-accounts-automatically-create-and-use-secrets-with-api-credentials)
+    - [Service Accounts Automatically Create and Attach Secrets with API Credentials](#service-accounts-automatically-create-and-attach-secrets-with-api-credentials)
     - [Creating a Secret Manually](#creating-a-secret-manually)
     - [Manually specifying a Secret to be Mounted on a Pod](#manually-specifying-a-secret-to-be-mounted-on-a-pod)
     - [Manually specifying an imagePullSecret](#manually-specifying-an-imagepullsecret)
-    - [Automatic use of Manually Created Secrets](#automatic-use-of-manually-created-secrets)
+    - [Arranging for imagePullSecrets to be Automatically Attached](#arranging-for-imagepullsecrets-to-be-automatically-attached)
+    - [Automatic Mounting of Manually Created Secrets](#automatic-mounting-of-manually-created-secrets)
   - [Details](#details)
     - [Restrictions](#restrictions)
     - [Consuming Secret Values](#consuming-secret-values)
@@ -64,19 +65,18 @@ a docker image. See [Secrets design document](../design/secrets.md) for more inf
 
 ## Overview of Secrets
 
+A Secret is an object that contains a small amount of sensitive data such as
+a password, a token, or a key.  Such information might otherwise be put in a
+Pod specification or in an image; putting it in a Secret object allows for
+more control over how it is used, and reduces the risk of accidental exposure.
 
-Creation of secrets can be manual (done by the user) or automatic (done by
-automation built into the cluster).
+Users can create secrets, and the system also creates some secrets.
 
-A secret can be used with a pod in two ways: either as files in a [volume](volumes.md) mounted on one or more of
+To use a secret, a pod needs to reference the secret.
+A secret can be used with a pod in two ways: eithe as files in a [volume](volumes.md) mounted on one or more of
 its containers, or used by kubelet when pulling images for the pod.
 
-To use a secret, a pod needs to reference the secret.  This reference
-can likewise be added manually or automatically.
-
-A single Pod may use various combination of the above options.
-
-### Service Accounts Automatically Create and Use Secrets with API Credentials
+### Service Accounts Automatically Create and Attach Secrets with API Credentials
 
 Kubernetes automatically creates secrets which contain credentials for
 accessing the API and it automatically modifies your pods to use this type of
@@ -112,9 +112,8 @@ are `value-1` and `value-2`, respectively, with carriage return and newline char
 
 Create the secret using [`kubectl create`](kubectl/kubectl_create.md).
 
-Once the secret is created, you can:
-  - create pods that automatically use it via a [Service Account](service-accounts.md).
-  - modify your pod specification to use the secret
+Once the secret is created, you can need to modify your pod to specify
+that it should use the secret.
 
 ### Manually specifying a Secret to be Mounted on a Pod
 
@@ -162,15 +161,22 @@ See another example of creating a secret and a pod that consumes that secret in
 
 Use of imagePullSecrets is described in the [images documentation](images.md#specifying-imagepullsecrets-on-a-pod)
 
-### Automatic use of Manually Created Secrets
+### Arranging for imagePullSecrets to be Automatically Attached
 
-*This feature is planned but not implemented.  See [issue
-9902](http://issue.k8s.io/9902).*
+You can manually create an imagePullSecret, and reference it from
+a serviceAccount.  Any pods created with that serviceAccount
+or that default to use that serviceAccount, will get have the imagePullSecret of the
+field set to that of the service account.
+See [here](service-accounts.md#adding-imagepullsecrets-to-a-service-account)
+ for a detailed explanation of that process.
 
-You can reference manually created secrets from a [Service Account](service-accounts.md).
-Then, pods which use that Service Account will have
-`volumeMounts` and/or `imagePullSecrets` added to them.
-The secrets will be mounted at **TBD**.
+
+### Automatic Mounting of Manually Created Secrets
+
+We plan to extend the service account behavior so that manually created
+secrets (e.g. one containing a token for accessing a github account)
+can be automatically attached to pods based on their service account.
+*This is not implemented yet.  See [issue 9902](http://issue.k8s.io/9902).*
 
 ## Details