diff --git a/README.rst b/README.rst
index d0f41828b..61b8c0842 100644
--- a/README.rst
+++ b/README.rst
@@ -699,6 +699,23 @@ dynamic paths generated by anchors break the authentication step.
 
 JSON and TEXT file types do not support anchors and thus have no such limitation.
 
+YAML Streams
+~~~~~~~~~~~~
+
+`YAML` supports having more than one document in a single file. `sops` does not. For this
+reason, the following file won't work in `sops`:
+
+.. code:: yaml
+
+	---
+	data: foo
+	---
+	data: bar
+
+If you try to encrypt this file with `sops`, it will ignore all documents except the first,
+effectively deleting them. `sops` does not support multi-document files, and until our YAML
+parser does, it is unlikely it will.
+
 Top-level arrays
 ~~~~~~~~~~~~~~~~
 `YAML` and `JSON` top-level arrays are not supported, because `sops` needs a top-level