[DOCS] Expanded conceptual information about datafeeds (elastic/x-pack-elasticsearch#3849)

Original commit: elastic/x-pack-elasticsearch@09a4229ed9

docs/en/ml/datafeeds.asciidoc

@@ -1,7 +1,40 @@
-[float]
 [[ml-dfeeds]]
 === {dfeeds-cap}
 
-Jobs can analyze either a one-off batch of data or continuously in real time.
+Machine learning jobs can analyze data that is stored in {es} or data that is
-{dfeeds-cap} retrieve data from {es} for analysis. Alternatively you can
+sent from some other source via an API. _{dfeeds-cap}_ retrieve data from {es}
-{ref}/ml-post-data.html[POST data] from any source directly to an API.
+for analysis, which is the simpler and more common scenario.
+
+If you create jobs in {kib}, you must use {dfeeds}. When you create a job, you
+select an index pattern and {kib} configures the {dfeed} for you under the
+covers. If you use {ml} APIs instead, you can create a {dfeed} by using the
+{ref}/ml-put-datafeed.html[create {dfeeds} API] after you create a job. You can
+associate only one {dfeed} with each job.
+
+For a description of all the {dfeed} properties, see
+{ref}/ml-datafeed-resource.html[Datafeed Resources].
+
+To start retrieving data from {es}, you must start the {dfeed}. When you start
+it, you can optionally specify start and end times. If you do not specify an
+end time, the {dfeed} runs continuously. You can start and stop {dfeeds} in
+{kib} or use the {ref}/ml-start-datafeed.html[start {dfeeds}] and
+{ref}/ml-stop-datafeed.html[stop {dfeeds}] APIs. A {dfeed} can be started and
+stopped multiple times throughout its lifecycle.
+
+[IMPORTANT]
+--
+When {security} is enabled, a {dfeed} stores the roles of the user who created
+or updated the {dfeed} at that time. This means that if those roles are updated,
+the {dfeed} subsequently runs with the new permissions that are associated with
+the roles. However, if the user’s roles are adjusted after creating or updating
+the {dfeed}, the {dfeed} continues to run with the permissions that were
+associated with the original roles.
+
+One way to update the roles that are stored within the {dfeed} without changing
+any other settings is to submit an empty JSON document ({}) to the
+{ref}/ml-update-datafeed.html[update {dfeed} API].
+--
+
+If the data that you want to analyze is not stored in {es}, you cannot use
+{dfeeds}. You can however send batches of data directly to the job by using the
+{ref}/ml-post-data.html[post data to jobs API].

docs/en/ml/limitations.asciidoc

@@ -163,14 +163,11 @@ For more information, see {ref}/ml-datafeed-resource.html[Datafeed Resources].
 
 When {security} is enabled, a {dfeed} stores the roles of the user who created
 or updated the {dfeed} **at that time**. This means that if those roles are
-updated then the {dfeed} will subsequently run with the new permissions associated
+updated then the {dfeed} subsequently runs with the new permissions that are
-with the roles. However, if the user's roles are adjusted after creating or
+associated with the roles. However, if the user's roles are adjusted after
-updating the {dfeed} then the {dfeed} will continue to run with the permissions
+creating or updating the {dfeed}, the {dfeed} continues to run with the
-associated with the original roles.
+permissions that were associated with the original roles. For more information,
-
+see <<ml-dfeeds>>. 
-A way to update the roles stored within the {dfeed} without changing any other
-settings is to submit an empty JSON document (`{}`) to the
-{ref}/ml-update-datafeed.html[update {dfeed} API].
 
 [float]
 === Forecasts cannot be created for population jobs

docs/en/ml/overview.asciidoc

@@ -5,6 +5,7 @@ include::analyzing.asciidoc[]
 include::forecasting.asciidoc[]
 include::buckets.asciidoc[]
 include::calendars.asciidoc[]
+include::datafeeds.asciidoc[]
 
 [[ml-concepts]]
 === Basic Machine Learning Terms
@@ -16,5 +17,4 @@ There are a few concepts that are core to {ml} in {xpack}. Understanding these
 concepts from the outset will tremendously help ease the learning process.
 
 include::jobs.asciidoc[]
-include::datafeeds.asciidoc[]
 include::architecture.asciidoc[]