diff --git a/docs/sample_config.yaml b/docs/sample_config.yaml
index 13482c16fe..be5ae548ec 100644
--- a/docs/sample_config.yaml
+++ b/docs/sample_config.yaml
@@ -259,10 +259,18 @@ listeners:
 
 # Whether to verify TLS certificates when sending federation traffic.
 #
+# This currently defaults to `false`, however this will change in
+# Synapse 1.0 when valid federation certificates will be required.
+#
 #federation_verify_certificates: true
 
-# Prevent federation certificate validation on the following whitelist
-# of domains. Only effective if federation_verify_certicates is true.
+# Skip federation certificate verification on the following whitelist
+# of domains.
+#
+# Note that this should only be used within the context of private
+# federation as it will otherwise break things.
+#
+# Only effective if federation_verify_certicates is `true`.
 #
 #federation_certificate_verification_whitelist:
 #  - lon.example.com