diff --git a/docs/user-guide/secrets/index.md b/docs/user-guide/secrets/index.md
index 8500238ed4..25eb5cfbee 100644
--- a/docs/user-guide/secrets/index.md
+++ b/docs/user-guide/secrets/index.md
@@ -124,9 +124,11 @@ $ kubectl create -f ./secret.yaml
 secret "mysecret" created
 ```
 
-**Encoding 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 (i.e. do not use `-b` option of `base64` which breaks long lines.)
+**Encoding 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.  When using the `base64` utility on Darwin/OS X users should avoid
+using the `-b` option to split long lines.  Conversely Linux users *should* add
+the option `-w 0` to `base64` commands.
 
 #### Decoding a Secret