Merge pull request #11235 from nik9000/seal_docs

Rewrote some _seal documentation

docs/reference/indices/seal.asciidoc

@@ -1,32 +1,32 @@
 [[indices-seal]]
 == Seal
 
-The seal API allows to flush one or more indices and adds a marker to
+The seal API flushes and adds a "seal" marker to the shards of one or more
-primaries and replicas if there are no pending write operations. The seal
+indices. The seal is used during recovery or restarts to skip the first and
-marker is used during recovery after a node restarts. If a replica is
+most costly phase of the process if all copies of the shard have the same seal.
-allocated on a node which already has a shard copy with the same seal as the
+No segment files need to be copied and the transaction log replay phase of the
-primary then no files will be copied during recovery. Sealing is a best effort
+recovery can start immediately which makes recovery much faster.
-operation. If write operations are ongoing while the sealing is in progress
-then writing the seal might fail on some copies.
 
-A seal marks a point in time snapshot (a low level Lucene commit). This mark
+There are two important points about seals:
-can be used to decide if the initial, rather resource heavy, recovery phase
+1. They are best effort in that if there are any outstanding write operations
-where segments or event the entire lucene index is copied over the network can
+while the seal operation is being performed then the shards which those writes
-be skipped. If the indices on both sides of the recovery have the same seal no
+target won't be sealed but all others will be. See below for more.
-segment files need to be copied and transaction log replay can start
+2. The seal breaks as soon as the shard issues a new lucene commit. Uncommitted
-immediately. The seal breaks as soon as the shard issues a new lucene commit,
+operations in the transaction log do not break the seal. That is because a seal
-uncommitted operations in the transaction log do not break the seal until they
+marks a point in time snapshot of the segments, a low level lucene commit.
-are committed.
+Practically that means that every write operation on the index will remove the
+seal.
 
-[source,js]
+[source,bash]
 --------------------------------------------------
-curl -XPOST 'http://localhost:9200/twitter/_seal'
+$ curl -XPOST 'http://localhost:9200/twitter/_seal'
 --------------------------------------------------
 
-The response contains details about for which shards a seal was written and
+The response contains details about which shards wrote the seal and the reason
-the reason in case of failure.
+in case they failed to write the seal.
 
-Response in case all copies of a shard successfully wrote the seal:
+Here is what it looks like when all copies single shard index successfully
+wrote the seal:
 
 [source,js]
 --------------------------------------------------
@@ -44,7 +44,7 @@ Response in case all copies of a shard successfully wrote the seal:
 --------------------------------------------------
 
 
-Response in case some copies of a shard failed:
+Here is what it looks like when one copy fails:
 
 [source,js]
 --------------------------------------------------
@@ -62,7 +62,7 @@ Response in case some copies of a shard failed:
 --------------------------------------------------
 
 
-Response in case all copies of a shard failed:
+Sometimes the failures can be shard wide and they'll look like this:
 
 [source,js]
 --------------------------------------------------