diff --git a/docs/plugins/repository-s3.asciidoc b/docs/plugins/repository-s3.asciidoc
index 531c5d16467..ddbe0b16cc6 100644
--- a/docs/plugins/repository-s3.asciidoc
+++ b/docs/plugins/repository-s3.asciidoc
@@ -208,8 +208,12 @@ The following settings are supported:
 
 `storage_class`::
 
-    Sets the S3 storage class type for the backup files. Values may be
-    `standard`, `reduced_redundancy`, `standard_ia`. Defaults to `standard`.
+    Sets the S3 storage class for objects stored in the snapshot repository.
+    Values may be `standard`, `reduced_redundancy`, `standard_ia`.
+    Defaults to `standard`. Changing this setting on an existing repository
+    only affects the storage class for newly created objects, resulting in a
+    mixed usage of storage classes. Additionally, S3 Lifecycle Policies can
+    be used to manage the storage class of existing objects.
     Due to the extra complexity with the Glacier class lifecycle, it is not
     currently supported by the plugin. For more information about the
     different classes, see http://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html[AWS Storage Classes Guide]