From 63a043676461d904b7447a1f494a1243ed154994 Mon Sep 17 00:00:00 2001
From: mzbeck <39967352+mzbeck@users.noreply.github.com>
Date: Thu, 26 Jul 2018 08:15:10 -0700
Subject: [PATCH] Update update-settings.asciidoc (#31378)

---
 .../cluster/update-settings.asciidoc          | 64 ++++++++++---------
 1 file changed, 34 insertions(+), 30 deletions(-)

diff --git a/docs/reference/cluster/update-settings.asciidoc b/docs/reference/cluster/update-settings.asciidoc
index 57be634e835..27d5cc316a6 100644
--- a/docs/reference/cluster/update-settings.asciidoc
+++ b/docs/reference/cluster/update-settings.asciidoc
@@ -1,9 +1,18 @@
 [[cluster-update-settings]]
 == Cluster Update Settings
 
-Allows to update cluster wide specific settings. Settings updated can
-either be persistent (applied across restarts) or transient (will not
-survive a full cluster restart). Here is an example:
+Use this API to review and change cluster-wide settings. 
+
+To review cluster settings:
+
+[source,js]
+--------------------------------------------------
+GET /_cluster/settings
+--------------------------------------------------
+// CONSOLE
+
+Updates to settings can be persistent, meaning they apply across restarts, or transient, where they don't 
+survive a full cluster restart. Here is an example of a persistent update:
 
 [source,js]
 --------------------------------------------------
@@ -16,7 +25,7 @@ PUT /_cluster/settings
 --------------------------------------------------
 // CONSOLE
 
-Or:
+This update is transient:
 
 [source,js]
 --------------------------------------------------
@@ -29,8 +38,7 @@ PUT /_cluster/settings?flat_settings=true
 --------------------------------------------------
 // CONSOLE
 
-The cluster responds with the settings updated. So the response for the
-last example will be:
+The response to an update returns the changed setting, as in this response to the transient example:
 
 [source,js]
 --------------------------------------------------
@@ -44,11 +52,14 @@ last example will be:
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\./"acknowledged": true,/]
 
-Resetting persistent or transient settings can be done by assigning a
-`null` value. If a transient setting is reset, the persistent setting
-is applied if available. Otherwise Elasticsearch will fallback to the setting
-defined at the configuration file or, if not existent, to the default
-value. Here is an example:
+You can reset persistent or transient settings by assigning a
+`null` value. If a transient setting is reset, the first one of these values that is defined is applied:
+
+* the persistent setting
+* the setting in the configuration file
+* the default value. 
+
+This example resets a setting:
 
 [source,js]
 --------------------------------------------------
@@ -61,8 +72,7 @@ PUT /_cluster/settings
 --------------------------------------------------
 // CONSOLE
 
-Reset settings will not be included in the cluster response. So
-the response for the last example will be:
+The response does not include settings that have been reset:
 
 [source,js]
 --------------------------------------------------
@@ -74,8 +84,8 @@ the response for the last example will be:
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\./"acknowledged": true,/]
 
-Settings can also be reset using simple wildcards. For instance to reset
-all dynamic `indices.recovery` setting a prefix can be used:
+You can also reset settings using wildcards. For example, to reset
+all dynamic `indices.recovery` settings:
 
 [source,js]
 --------------------------------------------------
@@ -88,25 +98,19 @@ PUT /_cluster/settings
 --------------------------------------------------
 // CONSOLE
 
-Cluster wide settings can be returned using:
-
-[source,js]
---------------------------------------------------
-GET /_cluster/settings
---------------------------------------------------
-// CONSOLE
 
 [float]
-=== Precedence of settings
+=== Order of Precedence
 
-Transient cluster settings take precedence over persistent cluster settings,
-which take precedence over settings configured in the `elasticsearch.yml`
-config file.
+The order of precedence for cluster settings is:
 
-For this reason it is preferrable to  use the `elasticsearch.yml` file only
-for local configurations, and set all cluster-wider settings with the
+1. transient cluster settings 
+2. persistent cluster settings
+3. settings in the `elasticsearch.yml` configuration file.
+
+It's best to use the `elasticsearch.yml` file only
+for local configurations, and set all cluster-wide settings with the
 `settings` API.
 
-A list of dynamically updatable settings can be found in the
-<<modules,Modules>> documentation.
+You can find the list of settings that you can dynamically update in <<modules,Modules>>.