From 83d7b48e1f9d0c859d2d007149d6e74df3f344ea Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Mon, 4 Dec 2023 12:21:24 -0600
Subject: [PATCH]  docs: Update source map documentation (#12131)

* attempt to address #11574

* attempt to address #11568

* address feedback from @simitt

* Update docs/source-map-how-to.asciidoc
---
 apm-server.yml                  | 10 +++-------
 docs/source-map-how-to.asciidoc | 23 +++++++++++++++++------
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/apm-server.yml b/apm-server.yml
index 590624c9724..35800aafd13 100644
--- a/apm-server.yml
+++ b/apm-server.yml
@@ -170,14 +170,10 @@ apm-server:
       # Note that values configured without a time unit will be interpreted as seconds.
       #cache.expiration: 5m
 
-      # Source maps may be fetched from Elasticsearch by using the output.elasticsearch configuration,
-      # and running apm-server standalone.
+      # Source map retrieval location.
       #
-      # Note: fetching source maps from Elasticsearch is not supported if apm-server is being managed by
-      # Fleet. This configuration is only applicable to standalone apm-servers, for backwards compatibility
-      # with source maps stored in Elasticsearch by older versions of apm-server. New source maps must now
-      # be uploaded via Kibana, and `apm-server.kibana` configured in standalone apm-servers for fetching
-      # them.
+      # If using an output other than Elasticsearch that is writing to Elasticsearch, you must
+      # set this option. If not set, the standard output elasticsearch configuration is used.
       #elasticsearch:
         # Array of hosts to connect to.
         # Scheme and port can be left out and will be set to the default (`http` and `9200`).
diff --git a/docs/source-map-how-to.asciidoc b/docs/source-map-how-to.asciidoc
index a0bc2a4675b..c8b03a785d2 100644
--- a/docs/source-map-how-to.asciidoc
+++ b/docs/source-map-how-to.asciidoc
@@ -95,19 +95,21 @@ module.exports = {
 
 [float]
 [[source-map-rum-upload]]
-=== Upload the source map to {kib}
+=== Upload the source map
+
+TIP: When uploading a source map, ensure that RUM support is enabled in the APM integration.
 
 {kib} exposes a {kibana-ref}/rum-sourcemap-api.html[source map endpoint] for uploading source maps.
 Source maps can be uploaded as a string, or as a file upload.
-Before uploading a source map, ensure that RUM support is enabled in the APM integration
 
 Let's look at two different ways to upload a source map: curl and a custom application.
 Each example includes the four fields necessary for APM Server to later map minified code to its source:
 
-* `service_name` - Should match the `serviceName` from step one
-* `service_version` - Should match the `serviceVersion` from step one
-* `bundle_filepath` - The absolute path of the final bundle as used in the web application
-* `sourcemap` - The location of the source map.
+* `service_name`: Should match the `serviceName` from step one.
+* `service_version`: Should match the `serviceVersion` from step one.
+* `bundle_filepath`: The absolute path of the final bundle as used in the web application.
+* `sourcemap`: The location of the source map.
+
 If you have multiple source maps, you'll need to upload each individually.
 
 [float]
@@ -164,3 +166,12 @@ request.post({url: 'http://localhost:5601/api/apm/sourcemaps',formData: formData
   }
 })
 ----
+
+[float]
+[[source-map-next]]
+=== What happens next
+
+Source maps are stored in {es}. When you upload a source map, a new {es} document is created
+containing the contents of the source map.
+When a RUM request comes in, APM Server will make use of these source map documents to apply the
+source map logic to the event's stack traces.