[DOCS] Explain flood stage watermark. (#57184)

* Changes for issue #36114.

* Adding stronger wording to the new note.

* Removing statement about typically not needting to set the read-only allow delete block.

* Replacing Elasticsearch with {es} variable.

docs/reference/index-modules.asciidoc

@@ -180,10 +180,14 @@ specific index module:
 
 `index.blocks.read_only_allow_delete`::
 
-    Similar to `index.blocks.read_only` but also allows deleting the index to
-    free up resources. The <<disk-based-shard-allocation,disk-based shard
+    Similar to `index.blocks.read_only`, but also allows deleting the index to
+    make more resources available. The <<disk-based-shard-allocation,disk-based shard
     allocator>> may add and remove this block automatically.
 
+Deleting documents from an index to release resources - rather than deleting the index itself - can increase the index size over time. When `index.blocks.read_only_allow_delete` is set to `true`, deleting documents is not permitted. However, deleting the index itself releases the read-only index block and makes resources available almost immediately.
+
+IMPORTANT: {es} adds and removes the read-only index block automatically when the disk utilization falls below the high watermark, controlled by <<cluster-routing-flood_stage,cluster.routing.allocation.disk.watermark.flood_stage>>.
+
 `index.blocks.read`::
 
     Set to `true` to disable read operations against the index.

docs/reference/modules/cluster/disk_allocator.asciidoc

@@ -1,7 +1,7 @@
 [[disk-based-shard-allocation]]
 ==== Disk-based shard allocation settings
 
-Elasticsearch considers the available disk space on a node before deciding
+{es} considers the available disk space on a node before deciding
 whether to allocate new shards to that node or to actively relocate shards away
 from that node.
 
@@ -16,16 +16,16 @@ file or updated dynamically on a live cluster with the
 `cluster.routing.allocation.disk.watermark.low`::
 
     Controls the low watermark for disk usage. It defaults to `85%`, meaning
-    that Elasticsearch will not allocate shards to nodes that have more than
+    that {es} will not allocate shards to nodes that have more than
     85% disk used. It can also be set to an absolute byte value (like `500mb`)
-    to prevent Elasticsearch from allocating shards if less than the specified
+    to prevent {es} from allocating shards if less than the specified
     amount of space is available. This setting has no effect on the primary
     shards of newly-created indices but will prevent their replicas from being allocated.
 
 `cluster.routing.allocation.disk.watermark.high`::
 
     Controls the high watermark. It defaults to `90%`, meaning that
-    Elasticsearch will attempt to relocate shards away from a node whose disk
+    {es} will attempt to relocate shards away from a node whose disk
     usage is above 90%. It can also be set to an absolute byte value (similarly
     to the low watermark) to relocate shards away from a node if it has less
     than the specified amount of free space. This setting affects the
@@ -37,23 +37,23 @@ file or updated dynamically on a live cluster with the
     changed in 8.0. This setting can be set to `true` to enable the
     disk watermarks for a single data node cluster (will become default in 8.0).
 
+[[cluster-routing-flood_stage]]
 `cluster.routing.allocation.disk.watermark.flood_stage`::
 +
 --
-Controls the flood stage watermark. It defaults to 95%, meaning that
-Elasticsearch enforces a read-only index block
+Controls the flood stage watermark, which defaults to 95%. {es} enforces a read-only index block
 (`index.blocks.read_only_allow_delete`) on every index that has one or more
-shards allocated on the node that has at least one disk exceeding the flood
-stage. This is a last resort to prevent nodes from running out of disk space.
-The index block is automatically released once the disk utilization falls below
+shards allocated on the node, and that has at least one disk exceeding the flood
+stage. This setting is a last resort to prevent nodes from running out of disk space.
+The index block is automatically released when the disk utilization falls below
 the high watermark.
 
-NOTE: You can not mix the usage of percentage values and byte values within
-these settings. Either all are set to percentage values, or all are set to byte
-values. This is so that we can we validate that the settings are internally
-consistent (that is, the low disk threshold is not more than the high disk
-threshold, and the high disk threshold is not more than the flood stage
-threshold).
+NOTE: You cannot mix the usage of percentage values and byte values within
+these settings. Either all values are set to percentage values, or all are set to byte
+values. This enforcement is so that {es} can validate that the settings are internally
+consistent, ensuring that the low disk threshold is less than the high disk
+threshold, and the high disk threshold is less than the flood stage
+threshold.
 
 An example of resetting the read-only index block on the `twitter` index:
 
@@ -69,7 +69,7 @@ PUT /twitter/_settings
 
 `cluster.info.update.interval`::
 
-    How often Elasticsearch should check on disk usage for each node in the
+    How often {es} should check on disk usage for each node in the
     cluster. Defaults to `30s`.
 
 NOTE: Percentage values refer to used disk space, while byte values refer to
@@ -105,4 +105,3 @@ future, even though the shard may really only consume a further 10GB of space.
 If the node's disks are close to a watermark then this may temporarily prevent
 other shards from moving onto the same node. Eventually the relocation will
 complete and then {es} will use the node's true disk usage statistics again.
-