diff --git a/docs/apm/images/apm-anomaly-alert.png b/docs/apm/images/apm-anomaly-alert.png
new file mode 100644
index 0000000000000..35ce9a2296c9c
Binary files /dev/null and b/docs/apm/images/apm-anomaly-alert.png differ
diff --git a/docs/apm/machine-learning.asciidoc b/docs/apm/machine-learning.asciidoc
index b203b8668072f..db2a1ef6e2da0 100644
--- a/docs/apm/machine-learning.asciidoc
+++ b/docs/apm/machine-learning.asciidoc
@@ -1,36 +1,61 @@
 [role="xpack"]
 [[machine-learning-integration]]
-===  integration
+=== Machine learning integration
 
 ++++
 <titleabbrev>Integrate with machine learning</titleabbrev>
 ++++
 
-The Machine Learning integration initiates a new job predefined to calculate anomaly scores on APM transaction durations.
-Jobs can be created per transaction type, and are based on the service's average response time.
+The Machine learning integration initiates a new job predefined to calculate anomaly scores on APM transaction durations.
+With this integration, you can quickly pinpoint anomalous transactions and see the health of
+any upstream and downstream services.
 
-After a machine learning job is created, results are shown in two places:
+Machine learning jobs are created per environment, and are based on a service's average response time.
+Because jobs are created at the environment level,
+you can add new services to your existing environments without the need for additional machine learning jobs.
 
-The transaction duration graph will show the expected bounds and add an annotation when the anomaly score is 75 or above.
+After a machine learning job is created, results are shown in two places:
 
+* The transaction duration chart will show the expected bounds and add an annotation when the anomaly score is 75 or above.
++
 [role="screenshot"]
 image::apm/images/apm-ml-integration.png[Example view of anomaly scores on response times in the APM app]
 
-Service maps will display a color-coded anomaly indicator based on the detected anomaly score.
-
+* Service maps will display a color-coded anomaly indicator based on the detected anomaly score.
++
 [role="screenshot"]
 image::apm/images/apm-service-map-anomaly.png[Example view of anomaly scores on service maps in the APM app]
 
 [float]
 [[create-ml-integration]]
-=== Create a new machine learning job
+=== Enable anomaly detection
+
+To enable machine learning anomaly detection:
+
+. From the Services overview, Traces overview, or Service Map tab,
+select **Anomaly detection**.
+
+. Click **Create ML Job**.
 
-To enable machine learning anomaly detection, first choose a service to monitor.
-Then, select **Integrations** > **Enable ML anomaly detection** and click **Create job**.
+. Machine learning jobs are created at the environment level.
+Select all of the service environments that you want to enable anomaly detection in.
+Anomalies will surface for all services and transaction types within the selected environments.
+
+. Click **Create Jobs**.
 
 That's it! After a few minutes, the job will begin calculating results;
-it might take additional time for results to appear on your graph.
-Jobs can be managed in *Machine Learning jobs management*.
+it might take additional time for results to appear on your service maps.
+Existing jobs can be managed in *Machine Learning jobs management*.
 
 APM specific anomaly detection wizards are also available for certain Agents.
 See the machine learning {ml-docs}/ootb-ml-jobs-apm.html[APM anomaly detection configurations] for more information.
+
+[float]
+[[warning-ml-integration]]
+=== Anomaly detection warning
+
+To make machine learning as easy as possible to set up,
+the APM app will warn you when filtered to an environment without a machine learning job.
+
+[role="screenshot"]
+image::apm/images/apm-anomaly-alert.png[Example view of anomaly alert in the APM app]
\ No newline at end of file