[7.x] [DOCS] Reformats the update by query API. (elastic#46199) (elastic#58700)

Co-authored-by: debadair <[email protected]>

Author: jrodewig

docs/reference/docs/delete-by-query.asciidoc

@@ -19,11 +19,6 @@ POST /twitter/_delete_by_query
 --------------------------------------------------
 // TEST[setup:big_twitter]
 
-[[docs-delete-by-query-api-request]]
-==== {api-request-title}
-
-`POST /<index>/_delete_by_query`
-
 ////
 
 [source,console-result]
@@ -49,6 +44,11 @@ POST /twitter/_delete_by_query
 // TESTRESPONSE[s/"took" : 147/"took" : "$body.took"/]
 ////
 
+[[docs-delete-by-query-api-request]]
+==== {api-request-title}
+
+`POST /<index>/_delete_by_query`
+
 [[docs-delete-by-query-api-desc]]
 ==== {api-description-title}
 
@@ -89,8 +89,7 @@ request to be refreshed. Unlike the delete API, it does not support
 
 If the request contains `wait_for_completion=false`, {es}
 performs some preflight checks, launches the request, and returns a
-<<docs-delete-by-query-task-api,`task`>>
-you can use to cancel or get the status of the task. {es} creates a
+<<tasks,`task`>> you can use to cancel or get the status of the task. {es} creates a
 record of this task as a document at `.tasks/task/${taskId}`. When you are 
 done with a task, you should delete the task document so {es} can reclaim the
 space.
@@ -227,9 +226,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeout]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=version]
 
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeout]
-
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
+include::{docdir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards]
 
 [[docs-delete-by-query-api-request-body]]
 ==== {api-request-body-title}
@@ -239,7 +236,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=wait_for_active_shards
   using the  <<query-dsl,Query DSL>>.
 
 
-[[docs-delete-by-quer-api-response-body]]
+[[docs-delete-by-query-api-response-body]]
 ==== Response body
 
 //////////////////////////
@@ -330,7 +327,7 @@ The number of requests per second effectively executed during the delete by quer
 `throttled_until_millis`::
 
 This field should always be equal to zero in a `_delete_by_query` response. It only
-has meaning when using the <<docs-delete-by-query-task-api, Task API>>, where it
+has meaning when using the <<tasks, Task API>>, where it
 indicates the next time (in milliseconds since epoch) a throttled request will be
 executed again in order to conform to `requests_per_second`.
 
@@ -541,7 +538,7 @@ Adding `slices` to `_delete_by_query` just automates the manual process used in
 the section above, creating sub-requests which means it has some quirks:
 
 * You can see these requests in the
-<<docs-delete-by-query-task-api,Tasks APIs>>. These sub-requests are "child"
+<<tasks,Tasks APIs>>. These sub-requests are "child"
 tasks of the task for the request with `slices`.
 * Fetching the status of the task for the request with `slices` only contains
 the status of completed slices.
@@ -655,7 +652,7 @@ you to delete that document.
 
 [float]
 [[docs-delete-by-query-cancel-task-api]]
-==== Cancel a delete by query operation
+===== Cancel a delete by query operation
 
 Any delete by query can be canceled using the <<tasks,task cancel API>>: