diff --git a/docs/plugins/repository-s3.asciidoc b/docs/plugins/repository-s3.asciidoc
index 6701d53c24047..44af56b886c63 100644
--- a/docs/plugins/repository-s3.asciidoc
+++ b/docs/plugins/repository-s3.asciidoc
@@ -34,10 +34,10 @@ PUT _snapshot/my_s3_repository
 [[repository-s3-client]]
 ==== Client Settings
 
-The client used to connect to S3 has a number of settings available. Client setting names are of
-the form `s3.client.CLIENT_NAME.SETTING_NAME` and specified inside `elasticsearch.yml`.  The
-default client name looked up by a `s3` repository is called `default`, but can be customized
-with the repository setting `client`. For example:
+The client that you use to connect to S3 has a number of settings available. The
+settings have the form `s3.client.CLIENT_NAME.SETTING_NAME`. The default client
+name that is looked up by an `s3` repository is `default`. It can be modified
+using the <<repository-s3-repository,repository setting>> `client`. For example:
 
 [source,js]
 ----
@@ -53,7 +53,11 @@ PUT _snapshot/my_s3_repository
 // CONSOLE
 // TEST[skip:we don't have s3 setup while testing this]
 
-Some settings are sensitive and must be stored in the {ref}/secure-settings.html[elasticsearch keystore].
+Most client settings can be added to the `elasticsearch.yml` configuration file
+with the exception of the secure settings, which you add to the {es} keystore.
+For more information about creating and updating the {es} keystore, see
+{ref}/secure-settings.html[Secure settings].
+
 For example, to use explicit AWS access keys:
 
 [source,sh]
@@ -62,16 +66,17 @@ bin/elasticsearch-keystore add s3.client.default.access_key
 bin/elasticsearch-keystore add s3.client.default.secret_key
 ----
 
-The following are the available client settings. Those that must be stored in the keystore
-are marked as `Secure`.
+The following list contains the available client settings. Those that must be
+stored in the keystore are marked as "secure"; the other settings belong in the
+`elasticsearch.yml` file.
 
-`access_key`::
+`access_key` ({ref}/secure-settings.html[Secure])::
 
-    An s3 access key. The `secret_key` setting must also be specified. (Secure)
+    An s3 access key. The `secret_key` setting must also be specified. 
 
-`secret_key`::
+`secret_key` ({ref}/secure-settings.html[Secure])::
 
-    An s3 secret key. The `access_key` setting must also be specified. (Secure)
+    An s3 secret key. The `access_key` setting must also be specified. 
 
 `endpoint`::
 
@@ -92,13 +97,13 @@ are marked as `Secure`.
 
     The port of a proxy to connect to s3 through.
 
-`proxy.username`::
+`proxy.username` ({ref}/secure-settings.html[Secure])::
 
-    The username to connect to the `proxy.host` with. (Secure)    
+    The username to connect to the `proxy.host` with.    
 
-`proxy.password`::
+`proxy.password` ({ref}/secure-settings.html[Secure])::
 
-    The password to connect to the `proxy.host` with. (Secure)    
+    The password to connect to the `proxy.host` with.   
 
 `read_timeout`::