diff --git a/dev_guide/secrets.adoc b/dev_guide/secrets.adoc
index 17fbcbaef3d9..0728be36f4dd 100644
--- a/dev_guide/secrets.adoc
+++ b/dev_guide/secrets.adoc
@@ -11,32 +11,130 @@ toc::[]
 
 == Overview
 
-The `Secrets` resource provides a mechanism to hold sensitive information such as passwords,
-client config files for OpenShift, `dockercfg`s, etc.  Secrets decouple sensitive content from
-the pods that use it and can be mounted into containers using a volume plugin or used by the
-system to perform actions on behalf of a pod.  This topic discusses important properties of 
-secrets and provides an overview on how developers can use them.
+The `Secret` object type provides a mechanism to hold sensitive information such
+as passwords, OpenShift client config files, `dockercfg` files, etc. Secrets
+decouple sensitive content from the pods that use it and can be mounted into
+containers using a volume plug-in or used by the system to perform actions on
+behalf of a pod. This topic discusses important properties of secrets and
+provides an overview on how developers can use them.
+
+====
+----
+{
+  "apiVersion": "v1",
+  "kind": "Secret",
+  "name": "mysecret",
+  "namespace": "myns",
+  "data": { <1>
+    "username": "dmFsdWUtMQ0K",
+    "password": "dmFsdWUtMg0KDQo="
+    }
+}
+----
+<1> The `data` field must match the keys in the the "DNS_SUBDOMAIN" value in `_docs/design/identifiers.md_`.
+====
 
 == Properties of secrets
+Key properties include:
+
+- Secret data can be referenced independently from its definition.
+- Secret data never comes to rest on the node. Volumes are backed by temporary file-storage facilities (tmpfs).
+- Secret data can be shared within a namespace.
 
 === Secrets and the Pod Lifecycle
+A secret must be created before the pods that depend on it.
 
-== Restrictions
+Containers read the secret from the files. If
+a secret is expected to be stored in an environment variable, then you
+must modify the image to populate the environment variable from the file before
+running the main program.
 
-=== Secret data keys
+Once a pod is created, its secret volumes do not change, even if the secret
+resource is modified. To change the secret used, the original pod must be
+deleted, and a new pod (perhaps with an identical PodSpec) must be created. An
+exception to this is when a node is rebooted and the secret data must be re-read
+from the API server. Updating a secret follows the same workflow as deploying a
+new container image. The
+link:https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/kubectl_rolling-update.md[`kubectl
+rollingupdate` command] can be used.
 
-=== Secrets and ServiceAccounts
+The `resourceVersion` value in a secret is not specified when it is referenced.
+Therefore, if a secret is updated at the same time as pods are starting,
+then the version of the secret will be used for the pod will not be defined.
+
+[NOTE]
+Currently, it is not possible to check the resource version of a secret object
+that was used when a pod was created. It is planned that pods will report this
+information, so that a controller could restart ones using a old
+`resourceVersion`. In the interim, do not update the data of existing secrets,
+but create new ones with distinct names.
 
 == Creating and Using Secrets
+When creating secrets:
+
+- Create a secret object with secret data
+- Create a pod with a volume of type `secret` and a container to mount the volume
+- Update the pod's service account to allow the reference to the secret.
+
+=== Creating Secrets
+To create a secret object, use the following command, where the json file is a
+predefined secret:
+
+====
+----
+$ oc create -f secret.json
+----
+====
 
 === Secrets in Volumes
 
 === Image Pull Secrets
+See link:dev_guide/image_pull_secrets.html[the image pull secrets] documentation
+for more information.
+
+== Restrictions
+Secret volume sources are validated to ensure that the specified object
+reference points to a `Secret` object. Therefore, a secret needs to be created
+before the pods that depend on it.
+
+Secret API objects reside in a namespace. They can only be referenced by pods in
+that same namespace.
 
-=== Working with Secrets with `oc`
+Individual secrets are limited to 1MB in size. This is to discourage the
+creation of large secrets that would exhaust apiserver and kubelet memory.
+However, creation of a number of smaller secrets could also exhaust memory.
+
+Currently, when mounting a secret, the service account for a pod must have the
+secret in the list of mountable secrets. If a secret is in a template pods will
+be rejected until the pod's service account is updated.
+
+=== Secret data keys
+Secret keys have to be in a DNS subdomain.
 
 == Examples
 
 === Example: Pod consuming secret data in volume
+The following is an example yaml of a pod comsuming data in a volume:
 
-=== Example: Pod with Image Pull Secret
+====
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: secret-example-pod
+spec:
+  containers:
+    - name: secret-test-container
+      image: busybox
+      command: [ "/bin/sh", "-c", "cat /etc/secret-volume/*" ]
+      volumeMounts:
+          # name must match the volume name below
+          - name: secret-volume
+            mountPath: /etc/secret-volume
+  volumes:
+    - name: secret-volume
+      secret:
+        secretName: test-secret
+  restartPolicy: Never
+----
+====