diff --git a/docs/yml.md b/docs/yml.md
index f8191766..aaa622cc 100644
--- a/docs/yml.md
+++ b/docs/yml.md
@@ -173,8 +173,12 @@ env_file:
   - /opt/secrets.env
 ```
 
+Compose expects each line in an env file to be in `VAR=VAL` format. Lines
+beginning with `#` (i.e. comments) are ignored, as are blank lines.
+
 ```
-RACK_ENV: development
+# Set Rails/Rack environment
+RACK_ENV=development
 ```
 
 ### extends