Improve docs for disk watermarks (#30249)

* Clarify that the low watermark does not affect brand-new shards.
* Replace ES -> Elasticsearch.
* Format to 80 columns.

Resolves #25163

docs/reference/modules/cluster/disk_allocator.asciidoc

@@ -1,9 +1,9 @@
 [[disk-allocator]]
 === Disk-based Shard Allocation
 
-Elasticsearch factors in the available disk space on a node before deciding
+Elasticsearch considers the available disk space on a node before deciding
-whether to allocate new shards to that node or to actively relocate shards
+whether to allocate new shards to that node or to actively relocate shards away
-away from that node.
+from that node.
 
 Below are the settings that can be configured in the `elasticsearch.yml` config
 file or updated dynamically on a live cluster with the
@@ -15,29 +15,33 @@ 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 ES will
+    Controls the low watermark for disk usage. It defaults to `85%`, meaning
-    not allocate new shards to nodes once they have more than 85% disk used. It
+    that Elasticsearch will not allocate shards to nodes that have more than
-    can also be set to an absolute byte value (like 500mb) to prevent ES from
+    85% disk used. It can also be set to an absolute byte value (like `500mb`)
-    allocating shards if less than the configured amount of space is available.
+    to prevent Elasticsearch 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 or, specifically, any shards that have
+    never previously been allocated.
 
 `cluster.routing.allocation.disk.watermark.high`::
 
-    Controls the high watermark. It defaults to 90%, meaning ES will attempt to
+    Controls the high watermark. It defaults to `90%`, meaning that
-    relocate shards to another node if the node disk usage rises above 90%. It can
+    Elasticsearch will attempt to relocate shards away from a node whose disk
-    also be set to an absolute byte value (similar to the low watermark) to
+    usage is above 90%. It can also be set to an absolute byte value (similarly
-    relocate shards once less than the configured amount of space is available on
+    to the low watermark) to relocate shards away from a node if it has less
-    the node.
+    than the specified amount of free space. This setting affects the
+    allocation of all shards, whether previously allocated or not.
 
 `cluster.routing.allocation.disk.watermark.flood_stage`::
 +
 --
-Controls the flood stage watermark. It defaults to 95%, meaning ES enforces
+Controls the flood stage watermark. It defaults to 95%, meaning that
-a read-only index block (`index.blocks.read_only_allow_delete`) on every
+Elasticsearch enforces a read-only index block
-index that has one or more shards allocated on the node that has at least
+(`index.blocks.read_only_allow_delete`) on every index that has one or more
-one disk exceeding the flood stage.  This is a last resort to prevent nodes
+shards allocated on the node that has at least one disk exceeding the flood
-from running out of disk space.  The index block must be released manually
+stage. This is a last resort to prevent nodes from running out of disk space.
-once there is enough disk space available to allow indexing operations to
+The index block must be released manually once there is enough disk space
-continue.
+available to allow indexing operations to continue.
 
 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
@@ -67,12 +71,12 @@ PUT /twitter/_settings
 `cluster.routing.allocation.disk.include_relocations`::
 
     Defaults to +true+, which means that Elasticsearch will take into account
-    shards that are currently being relocated to the target node when computing a
+    shards that are currently being relocated to the target node when computing
-    node's disk usage. Taking relocating shards' sizes into account may, however,
+    a node's disk usage. Taking relocating shards' sizes into account may,
-    mean that the disk usage for a node is incorrectly estimated on the high side,
+    however, mean that the disk usage for a node is incorrectly estimated on
-    since the relocation could be 90% complete and a recently retrieved disk usage
+    the high side, since the relocation could be 90% complete and a recently
-    would include the total size of the relocating shard as well as the space
+    retrieved disk usage would include the total size of the relocating shard
-    already used by the running relocation.
+    as well as the space already used by the running relocation.
 
 
 NOTE: Percentage values refer to used disk space, while byte values refer to