review feedback

docs/reference/search/request/from-size.asciidoc

@@ -2,19 +2,12 @@
 [[paginate-search-results]]
 === Paginate search results
 
-By default, the search API returns the top 10 matching documents, 
-starting with the most-relevant document.
+By default, the search API returns the top 10 matching documents.
 
 To paginate through a larger set of results, you can use the search API's `size`
-and `from` parameters. The `size` parameter is the number of matching documents to return. The `from` parameter is a zero-indexed offset from the beginning of the complete result set that indicates the document you want to start with. 
-
-[IMPORTANT]
-====
-The combined document count, including offset and and returned documents, for
-the `from` and `size` parameters cannot exceed the
-<<index-max-result-window,`index.max_result_window`>> index setting, which
-defaults to 10,000 documents.
-====
+and `from` parameters. The `size` parameter is the number of matching documents
+to return. The `from` parameter is a zero-indexed offset from the beginning of
+the complete result set that indicates the document you want to start with.
 
 .*Example*
 [%collapsible]
@@ -39,9 +32,21 @@ GET /_search
 ----
 ====
 
+By default, you cannot page through more than 10,000 documents using the `from`
+and `size` parameters. This limit is set using the
+<<index-max-result-window,`index.max_result_window`>> index setting.
+
+Paging deeply or requesting many results at once can result in slow searches.
+Results are sorted before being returned. Because search requests usually span
+multiple shards, each shard must generate its own sorted results. These separate
+results must then be combined and sorted to ensure that the overall sort order
+is correct.
+
+As an alternative to deep paging, we recommend using the
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
+
 WARNING: {es} uses Lucene's internal doc IDs as tie-breakers. These internal
 doc IDs can be completely different across replicas of the same
 data. When paginating, you might occasionally see that documents with the same
-sort values are not ordered consistently. For deep scrolling, it is more
-efficient to use the <<request-body-search-scroll,Scroll>> or 
-<<request-body-search-search-after,Search After>> APIs.
+sort values are not ordered consistently.

docs/reference/search/search.asciidoc

@@ -87,13 +87,19 @@ both parameters are specified, only the query parameter is used.
 include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
 +
 --
-[IMPORTANT]
-====
-The combined document count, including offset and and returned documents, for
-the `from` and `size` parameters cannot exceed the
-<<index-max-result-window,`index.max_result_window`>> index setting, which
-defaults to 10,000 documents.
-====
+By default, you cannot page through more than 10,000 documents using the `from`
+and `size` parameters. This limit is set using the
+<<index-max-result-window,`index.max_result_window`>> index setting.
+
+Paging deeply or requesting many results at once can result in slow searches.
+Results are sorted before being returned. Because search requests usually span
+multiple shards, each shard must generate its own sorted results. These separate
+results must then be combined and sorted to ensure that the overall order is
+correct.
+
+As an alternative to deep paging, we recommend using the
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
 
 [IMPORTANT]
 ====
@@ -178,13 +184,19 @@ parameter. If both parameters are specified, only the query parameter is used.
 (Optional, integer) Defines the number of hits to return. Defaults to `10`.
 +
 --
-[IMPORTANT]
-====
-The combined document count, including offset and and returned documents, for
-the `from` and `size` parameters cannot exceed the
-<<index-max-result-window,`index.max_result_window`>> index setting, which
-defaults to 10,000 documents.
-====
+By default, you cannot page through more than 10,000 documents using the `from`
+and `size` parameters. This limit is set using the
+<<index-max-result-window,`index.max_result_window`>> index setting.
+
+Paging deeply or requesting many results at once can result in slow searches.
+Results are sorted before being returned. Because search requests usually span
+multiple shards, each shard must generate its own sorted results. These separate
+results must then be combined and sorted to ensure that the overall order is
+correct.
+
+As an alternative to deep paging, we recommend using the
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
 
 [IMPORTANT]
 ====
@@ -295,13 +307,19 @@ both parameters are specified, only the query parameter is used.
 include::{docdir}/rest-api/common-parms.asciidoc[tag=from]
 +
 --
-[IMPORTANT]
-====
-The combined document count, including offset and and returned documents, for
-the `from` and `size` parameters cannot exceed the
-<<index-max-result-window,`index.max_result_window`>> index setting, which
-defaults to 10,000 documents.
-====
+By default, you cannot page through more than 10,000 documents using the `from`
+and `size` parameters. This limit is set using the
+<<index-max-result-window,`index.max_result_window`>> index setting.
+
+Paging deeply or requesting many results at once can result in slow searches.
+Results are sorted before being returned. Because search requests usually span
+multiple shards, each shard must generate its own sorted results. These separate
+results must then be combined and sorted to ensure that the overall order is
+correct.
+
+As an alternative to deep paging, we recommend using the
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
 
 [IMPORTANT]
 ====
@@ -333,13 +351,19 @@ If both parameters are specified, only the query parameter is used.
 (Optional, integer) The number of hits to return. Defaults to `10`.
 +
 --
-[IMPORTANT]
-====
-The combined document count, including offset and and returned documents, for
-the `from` and `size` parameters cannot exceed the
-<<index-max-result-window,`index.max_result_window`>> index setting, which
-defaults to 10,000 documents.
-====
+By default, you cannot page through more than 10,000 documents using the `from`
+and `size` parameters. This limit is set using the
+<<index-max-result-window,`index.max_result_window`>> index setting.
+
+Paging deeply or requesting many results at once can result in slow searches.
+Results are sorted before being returned. Because search requests usually span
+multiple shards, each shard must generate its own sorted results. These separate
+results must then be combined and sorted to ensure that the overall order is
+correct.
+
+As an alternative to deep paging, we recommend using the
+<<request-body-search-scroll,Scroll>> or
+<<request-body-search-search-after,Search After>> APIs.
 
 [IMPORTANT]
 ====