diff --git a/docs/design/secrets.md b/docs/design/secrets.md
index ac8776bd820..dc5961833a8 100644
--- a/docs/design/secrets.md
+++ b/docs/design/secrets.md
@@ -273,7 +273,8 @@ type Secret struct {
     ObjectMeta
 
     // Data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.
-    // The serialized form of the secret data is a base64 encoded string.
+    // The serialized form of the secret data is a base64 encoded string,
+    // representing the arbitrary (possibly non-string) data value here.
     Data map[string][]byte `json:"data,omitempty"`
 
     // Used to facilitate programatic handling of secret data.
@@ -398,8 +399,9 @@ To create a pod that uses an ssh key stored as a secret, we first need to create
 }
 ```
 
-**Note:** The values of secret data are encoded as base64-encoded strings.  Newlines are not
-valid within these strings and must be omitted.
+**Note:** The serialized JSON and YAML values of secret data are encoded as
+base64 strings.  Newlines are not valid within these strings and must be
+omitted.
 
 Now we can create a pod which references the secret with the ssh key and consumes it in a volume:
 
diff --git a/pkg/api/types.go b/pkg/api/types.go
index ba44ecbd290..26123027258 100644
--- a/pkg/api/types.go
+++ b/pkg/api/types.go
@@ -1330,7 +1330,8 @@ type Secret struct {
 	ObjectMeta `json:"metadata,omitempty"`
 
 	// Data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.
-	// The serialized form of the secret data is a base64 encoded string.
+	// The serialized form of the secret data is a base64 encoded string,
+	// representing the arbitrary (possibly non-string) data value here.
 	Data map[string][]byte `json:"data,omitempty"`
 
 	// Used to facilitate programatic handling of secret data.
diff --git a/pkg/api/v1beta1/types.go b/pkg/api/v1beta1/types.go
index e07a980ec8f..187b8853d3f 100644
--- a/pkg/api/v1beta1/types.go
+++ b/pkg/api/v1beta1/types.go
@@ -1113,7 +1113,8 @@ type Secret struct {
 	TypeMeta `json:",inline"`
 
 	// Data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.
-	// The serialized form of the secret data is a base64 encoded string.
+	// The serialized form of the secret data is a base64 encoded string,
+	// representing the arbitrary (possibly non-string) data value here.
 	Data map[string][]byte `json:"data,omitempty" description:"data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.  Each value must be a base64 encoded string"`
 
 	// Used to facilitate programatic handling of secret data.
diff --git a/pkg/api/v1beta2/types.go b/pkg/api/v1beta2/types.go
index 6d56326e54c..03fdefa27fc 100644
--- a/pkg/api/v1beta2/types.go
+++ b/pkg/api/v1beta2/types.go
@@ -1116,7 +1116,8 @@ type Secret struct {
 	TypeMeta `json:",inline"`
 
 	// Data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.
-	// The serialized form of the secret data is a base64 encoded string.
+	// The serialized form of the secret data is a base64 encoded string,
+	// representing the arbitrary (possibly non-string) data value here.
 	Data map[string][]byte `json:"data,omitempty" description:"data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.  Each value must be a base64 encoded string"`
 
 	// Used to facilitate programatic handling of secret data.
diff --git a/pkg/api/v1beta3/types.go b/pkg/api/v1beta3/types.go
index 2408527385e..0d19dd495cf 100644
--- a/pkg/api/v1beta3/types.go
+++ b/pkg/api/v1beta3/types.go
@@ -1267,7 +1267,8 @@ type Secret struct {
 	ObjectMeta `json:"metadata,omitempty"`
 
 	// Data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.
-	// The serialized form of the secret data is a base64 encoded string.
+	// The serialized form of the secret data is a base64 encoded string,
+	// representing the arbitrary (possibly non-string) data value here.
 	Data map[string][]byte `json:"data,omitempty" description:"data contains the secret data.  Each key must be a valid DNS_SUBDOMAIN.  Each value must be a base64 encoded string"`
 
 	// Used to facilitate programatic handling of secret data.