Splunk docs polishing

Author: David O'Sullivan

docs/framework-splunk_otel_java_agent.md

@@ -1,9 +1,8 @@
 # Splunk Distribution of OpenTelemetry Java Instrumentation
 
-The Splunk OpenTelemetry Java Agent buildpack framework will cause an application to be automatically instrumented
-with the [Splunk distribution of OpenTelemetry Java Instrumentation](https://github.com/signalfx/splunk-otel-java).
-
-Trace data will be sent directly to Splunk Observability Cloud. 
+This buildpack framework automatically instruments your Java application
+with the [Splunk distribution of OpenTelemetry Java Instrumentation](https://github.com/signalfx/splunk-otel-java)
+to send trace data to Splunk Observability Cloud.
 
 <table>
   <tr>
@@ -16,15 +15,18 @@ Trace data will be sent directly to Splunk Observability Cloud.
   </tr>
 </table>
 
-Tags are printed to standard output by the buildpack detect script
+The buildpack detect script prints tags to standard output.
 
 ## User-Provided Service
 
-Users are currently expected to `create-user-provided-service` (cups) of the collector
-and bind it to their application. The service MUST contain the string `splunk-o11y`.
+
+Provide your own "user provided service" (cups) instance and bind
+it to your application.
+
+The service name MUST contain the string `splunk-o11y`.
 
 For example, to create a service named `splunk-o11y` that represents Observability Cloud 
-realm `us0` and represents a user environment named `cf-demo`, you could use the following
+realm `us0` and represents a user environment named `cf-demo`, use the following
 commands:
 
 ```
@@ -34,27 +36,29 @@ $ cf bind-service myApp splunk-o11y
 $ cf restage myApp
 ```
 
-The `credential` field of the service should provide these entries:
+Provide the following values using the `credential` field of the service:
 
 | Name                   | Required? | Description
 |------------------------|-----------| -----------
-| `splunk.access.token`  | Yes       | The Splunk [org access token](https://docs.splunk.com/observability/admin/authentication-tokens/org-tokens.html).
-| `splunk.realm`         | Yes       | The Splunk realm where data will be sent. This is commonly `us0` or `eu0` etc.
-| `otel.*` or `splunk.*` | Optional  | All additional credentials starting with these prefixes will be appended to the application's JVM arguments as system properties.
+| `splunk.access.token`  | Yes       | Splunk [org access token](https://docs.splunk.com/observability/admin/authentication-tokens/org-tokens.html).
+| `splunk.realm`         | Yes       | Splunk realm where data will be sent. This is commonly `us0`, `eu0`, and so on. See [Available regions or realms](https://docs.splunk.com/observability/en/get-started/service-description.html#available-regions-or-realms) for more information.
+| `otel.*` or `splunk.*` | Optional  | All additional credentials starting with these prefixes are appended to the application's JVM arguments as system properties.
 
 ### Choosing a version
 
-Most users should skip this and simply use the latest version of the agent available (the default).
-To override the default and choose a specific version, you can use the `JBP_CONFIG_*` mechanism
+To override the default and choose a specific version, use the `JBP_CONFIG_*` mechanism
 and set the `JBP_CONFIG_SPLUNK_OTEL_JAVA_AGENT` environment variable for your application.
 
-For example, to use version 1.16.0 of the Splunk OpenTelemetry Java Instrumentation, you
-could run:
+For example, to use version 1.16.0 of the Splunk OpenTelemetry Java Instrumentation, run:
+
 ```
 $ cf set-env testapp JBP_CONFIG_SPLUNK_OTEL_JAVA_AGENT '{version: 1.16.0}'
 ```
- 
+
+In most cases you can use the latest or default version of the agent available.
+
 # Additional Resources
 
 * [Splunk Observability](https://www.splunk.com/en_us/products/observability.html)
+* [Official documentation of the Splunk Java agent](https://docs.splunk.com/observability/en/gdi/get-data-in/application/java/get-started.html)
 * [Splunk Distribution of OpenTelemetry Java](https://github.com/signalfx/splunk-otel-java) on GitHub