diff --git a/docs/changing_configuration.md b/docs/changing_configuration.md
index 14d6f28c71..6b5a44b22f 100644
--- a/docs/changing_configuration.md
+++ b/docs/changing_configuration.md
@@ -12,3 +12,7 @@
 
 * Apply the rolling-update `kops rolling-update cluster ${NAME} --yes`
 
+NOTE: rolling-update does not yet perform a real rolling update - it just shuts down machines in sequence with a delay;
+ there will be downtime [Issue #37](https://github.com/kubernetes/kops/issues/37)
+We have implemented a new feature that does drain and validate nodes.  This feature is experimental, and you can use the new feature by setting `export KOPS_FEATURE_FLAGS="+DrainAndValidateRollingUpdate"`.
+
diff --git a/docs/instance_groups.md b/docs/instance_groups.md
index 29c22f94e7..fa74c85d05 100644
--- a/docs/instance_groups.md
+++ b/docs/instance_groups.md
@@ -50,6 +50,7 @@ Then restart the machines with: `kops rolling-update cluster --yes`
 
 NOTE: rolling-update does not yet perform a real rolling update - it just shuts down machines in sequence with a delay;
  there will be downtime [Issue #37](https://github.com/kubernetes/kops/issues/37)
+We have implemented a new feature that does drain and validate nodes.  This feature is experimental, and you can use the new feature by setting `export KOPS_FEATURE_FLAGS="+DrainAndValidateRollingUpdate"`.
 
 ## Resize an instance group
 
diff --git a/docs/upgrade.md b/docs/upgrade.md
index 5b3580323e..4a4828b48d 100644
--- a/docs/upgrade.md
+++ b/docs/upgrade.md
@@ -24,3 +24,8 @@ node restart), but currently you must:
 * `kops rolling-update cluster $NAME` to preview, then `kops rolling-update cluster $NAME --yes`
 
 Upgrade uses the latest Kubernetes version considered stable by kops, defined in `https://github.com/kubernetes/kops/blob/master/channels/stable`.
+
+NOTE: rolling-update does not yet perform a real rolling update - it just shuts down machines in sequence with a delay;
+ there will be downtime [Issue #37](https://github.com/kubernetes/kops/issues/37)
+We have implemented a new feature that does drain and validate nodes.  This feature is experimental, and you can use the new feature by setting `export KOPS_FEATURE_FLAGS="+DrainAndValidateRollingUpdate"`.
+