diff --git a/docs/reference/ml/apis/update-datafeed.asciidoc b/docs/reference/ml/apis/update-datafeed.asciidoc
index 63878913c7f1a..cb05493162ba4 100644
--- a/docs/reference/ml/apis/update-datafeed.asciidoc
+++ b/docs/reference/ml/apis/update-datafeed.asciidoc
@@ -10,21 +10,37 @@
 
 Updates certain properties of a {dfeed}.
 
-==== Request
+
+[[ml-update-datafeed-request]]
+==== {api-request-title}
 
 `POST _ml/datafeeds/<feed_id>/_update`
 
-===== Description
 
-NOTE: If you update the `delayed_data_check_config` property, you must stop and
-start the {dfeed} for the change to be applied.
+[[ml-update-datafeed-prereqs]]
+==== {api-prereq-title}
+
+* If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
+cluster privileges to use this API. For more information, see
+{stack-ov}/security-privileges.html[Security privileges].
+
+
+[[ml-update-datafeed-desc]]
+==== {api-description-title}
+
+If you update a {datafeed} property, you must stop and start the {dfeed} for the 
+change to be applied.
 
-==== Path Parameters
 
-`feed_id` (required)::
-  (string) Identifier for the {dfeed}
+[[ml-update-datafeed-path-parms]]
+==== {api-path-parms-title}
 
-==== Request Body
+`feed_id`::
+  (Required, string) Identifier for the {dfeed}.
+
+
+[[ml-update-datafeed-request-body]]
+==== {api-request-body-title}
 
 The following properties can be updated after the {dfeed} is created:
 
@@ -41,17 +57,18 @@ The following properties can be updated after the {dfeed} is created:
   the size of the window. See <<ml-datafeed-delayed-data-check-config>>.  
 
 `frequency`::
-  (time units) The interval at which scheduled queries are made while the
-  {dfeed} runs in real time. The default value is either the bucket span for short
-  bucket spans, or, for longer bucket spans, a sensible fraction of the bucket
-  span. For example: `150s`.
+  (Optional, <<time-units, time units>>) The interval at which scheduled queries 
+  are made while the {dfeed} runs in real time. The default value is either the 
+  bucket span for short bucket spans, or, for longer bucket spans, a sensible 
+  fraction of the bucket span. For example: `150s`.
 
 `indices`::
   (array) An array of index names. Wildcards are supported. For example:
   `["it_ops_metrics", "server*"]`.
 
 `job_id`::
- (string) A numerical character string that uniquely identifies the job.
+ (Optional, string) A numerical character string that uniquely identifies the
+ {anomaly-job}.
 
 `query`::
   (object) The {es} query domain-specific language (DSL). This value
@@ -59,11 +76,21 @@ The following properties can be updated after the {dfeed} is created:
   options that are supported by {es} can be used, as this object is
   passed verbatim to {es}. By default, this property has the following
   value: `{"match_all": {"boost": 1}}`.
++
+--
+WARNING: If you change the query, then the analyzed data will also be changed, 
+therefore the required time to learn might be long and the understandability of 
+the results is unpredictable.
+If you want to make significant changes to the source data, we would recommend 
+you clone it and create a second job containing the amendments. Let both run in 
+parallel and close one when you are satisfied with the results of the other job.
+--
 
 `query_delay`::
-  (time units) The number of seconds behind real-time that data is queried. For
-  example, if data from 10:04 a.m. might not be searchable in {es} until
-  10:06 a.m., set this property to 120 seconds. The default value is `60s`.
+  (Optional, <<time-units, time units>>) The number of seconds behind real-time 
+  that data is queried. For example, if data from 10:04 a.m. might not be 
+  searchable in {es} until 10:06 a.m., set this property to 120 seconds. The 
+  default value is `60s`.
 
 `script_fields`::
   (object) Specifies scripts that evaluate custom expressions and returns
@@ -77,17 +104,10 @@ The following properties can be updated after the {dfeed} is created:
   (unsigned integer) The `size` parameter that is used in {es} searches.
   The default value is `1000`.
 
-For more information about these properties,
-see <<ml-datafeed-resource>>.
-
-
-==== Authorization
-
-If {es} {security-features} are enabled, you must have `manage_ml`, or `manage`
-cluster privileges to use this API. For more information, see
-{stack-ov}/security-privileges.html[Security Privileges].
+For more information about these properties, see <<ml-datafeed-resource>>.
 
 
+[[ml-update-datafeed-security]]
 ==== Security Integration
 
 When {es} {security-features} are enabled, your {dfeed} remembers which roles the
@@ -95,7 +115,8 @@ user who updated it had at the time of update and runs the query using those
 same roles.
 
 
-==== Examples
+[[ml-update-datafeed-example]]
+==== {api-examples-title}
 
 The following example updates the query for the `datafeed-total-requests`
 {dfeed} so that only log entries of error level are analyzed:
@@ -138,4 +159,4 @@ with the updated values:
   }
 }
 ----
-// TESTRESPONSE[s/"query.boost": "1.0"/"query.boost": $body.query.boost/]
+// TESTRESPONSE[s/"query.boost": "1.0"/"query.boost": $body.query.boost/]
\ No newline at end of file