Adopt review comments on doc updates (helidon-io#4627)

Author: tjquinno

docs/includes/attributes.adoc

@@ -76,6 +76,7 @@ endif::[]
 :version-lib-oracle-ucp: {version-lib-oracle-jdbc}
 :version-plugin-jib: 0.10.1
 :version-plugin-jandex: 1.0.6
+:version-lib-micrometer: 1.6.6
 
 :jdk-version: 17
 
@@ -258,5 +259,7 @@ endif::[]
 
 :micrometer-url: https://micrometer.io
 :micrometer-api-url: https://micrometer.io/docs/concepts
+:micrometer-javadoc-base-url: https://javadoc.io/doc/io.micrometer
+:micrometer-javadoc-registry-prometheus-base-url: {micrometer-javadoc-base-url}/micrometer-registry-prometheus/{version-lib-micrometer}/io/micrometer/prometheus
 
 endif::attributes-included[]

docs/includes/metrics/metrics-capable-components.adoc

@@ -77,9 +77,10 @@ endif::[]
 As you plan and write Helidon components and applications,
 you make some choices about exactly how your code will use metrics.
 This document gives some background information,
-describes the choices you face, explains their ramifications, and provides some code examples.
+describes each option and its effect, and provides some code examples.
 
 == Usage
+This section helps you decide how incorporate metrics into your software by describing the categories of metrics usage, explaining generally how Helidon implements metrics, and illustrating how to write the metrics-related code accordingly.
 
 === Categorizing Metrics Usage
 We can place each Helidon component and Helidon application into one of three categories based on how it relies on metrics.
@@ -103,10 +104,10 @@ The type of module dictates the compile-time dependency you declare in the proje
 |metrics-dependent
 |===
 
-Whenever possible, if your component or app uses metrics write it as metrics-capable code.
+Whenever possible, if your component or application uses metrics, then write it as metrics-capable code.
 
 === Understanding the Two Metrics Implementations
-Helidon provides two metrics implementations.
+Helidon provides two metrics implementations:
 
 * _Full-featured_ metrics allows registering, removing, and updating metrics and observing metrics' changing values.
 The `helidon-metrics` component contains full-featured metrics.
@@ -292,8 +293,8 @@ Helidon returns either a full-featured `RegistryFactory` or a minimal one, depen
 // tag::writing-code-ending[]
 
 == Examples
-=== An Example: Docker Images
-Here is an example showing how useful metrics-capable code can be.
+
+The following example shows how useful metrics-capable code can be in the context of building Docker images.
 
 You (or others) could assemble a Docker image with your metrics-capable app as its top layer or your metrics-capable component in a middle layer, built on a lower  layer containing several Helidon modules including the full metrics implementation.
 When that Docker image runs, your app will run with full-featured metrics support.

docs/includes/metrics/metrics-config.adoc

@@ -81,7 +81,7 @@ Helidon updates and reports a metric only if two conditions hold:
 ** there is no `include` regex pattern, or
 ** the metric name matches the `include` pattern.
 
-[CAUTION]
+[NOTE]
 ====
 Make sure any `include` regex pattern you specify matches _all_ the metric names you want to capture.
 ====
@@ -150,14 +150,14 @@ endif::[]
 
 [#config-rest-request]
 ifdef::mp-flavor[]
-==== Enable `REST.request` metrics
+==== Enable `REST.request` Metrics
 
 .Controlling REST request metrics
 [source,properties]
 ----
 metrics.rest-request-enabled=true
 ----
-Helidon will automatically register and update `SimpleTimer` metrics for every REST endpoint in your service.
+Helidon automatically registers and updates `SimpleTimer` metrics for every REST endpoint in your service.
 endif::[]
 
 // end::config-examples[]

docs/includes/metrics/metrics-shared.adoc

@@ -57,7 +57,7 @@ ifdef::mp-flavor[each of these.]
 ifdef::se-flavor[this.]
 
 === Categorizing Types of Metrics
-Helidon distinguishes among three general _types_, or scopes, of metrics, as described in the MP metrics specification.
+Helidon distinguishes among three general _types_, or scopes, of metrics, as described in the link:{microprofile-metrics-spec-url}[MP metrics specification].
 
 .Types (scopes) of metrics
 [%autowidth]
@@ -128,7 +128,7 @@ curl -s -H 'Accept: application/json' -X GET http://localhost:8080/metrics/
 }
 ----
 
-In addition to your application metrics the reports contain other
+In addition to your application metrics, the reports contain other
 metrics of interest such as system and VM information.
 
 // end::usage-body[]

docs/includes/metrics/micrometer-shared.adoc

@@ -124,7 +124,7 @@ Note that the first config example is equivalent to the default Helidon Micromet
 
 The configuration keys that are valid for the `builtin-registries` child entries depend on the type of Micrometer meter
 registry.
-For example, the Prometheus meter registry supports the `prefix` configuration setting but other meter registries might not and might support other settings.
+For example, support in Helidon for the link:{micrometer-javadoc-registry-prometheus-base-url}/PrometheusConfig.html[Prometheus meter registry] respects the `prefix` configuration setting but other meter registries might not and might support other settings.
 Refer to the documentation for the meter registry you want to configure to find out what items apply to that registry
 type.
 

docs/includes/openapi.adoc

@@ -29,7 +29,7 @@ ifdef::se-flavor[OpenAPI support in Helidon {flavor-uc} draws its inspiration fr
 The OpenAPI support in Helidon {flavor-uc} performs two main tasks:
 
 * Build an in-memory model of the REST API your service implements.
-* Expose the model in text format (typically yaml) via the `/openapi` endpoint.
+* Expose the model in text format (typically YAML) via the `/openapi` endpoint.
 
 To construct the model, Helidon gathers information about the service API from whichever of these sources are present in the application:
 

docs/mp/metrics/micrometer.adoc

@@ -36,6 +36,9 @@ include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=intro]
 include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=prereq]
 
 == Usage
+Your application registers and updates Micrometer meters using annotations or direct use of the Micrometer API.
+
+Your users retrieve Micrometer meters using an endpoint which Helidon creates automatically.
 
 === Registering and Updating Meters
 To use Micrometer support, you can simply add the Micrometer `@Timed` and `@Counted` annotations to methods in your application. Helidon automatically registers those meters with the Micrometer composite `MeterRegistry`.
@@ -50,6 +53,7 @@ include::{rootdir}/includes/metrics/micrometer-shared.adoc[tag=accessing-endpoin
 
 
 == API
+To incorporate Micrometer metrics into your code, you will work with two APIs: a small one specific to Helidon, and the Micrometer API itself.
 
 === The Helidon Micrometer API
 Helidon automatically registers and updates meters associated with methods in your service where you add the Micrometer annotations.

docs/se/metrics/micrometer.adoc

@@ -36,6 +36,9 @@ include::{rootdir}/includes/metrics/micrometer-shared.adoc[tags=intro]
 include::{rootdir}/includes/metrics/micrometer-shared.adoc[tags=prereq]
 
 == Usage
+Your application registers and updates Micrometer meters using annotations or direct use of the Micrometer API.
+
+Your users retrieve Micrometer meters using an endpoint which Helidon creates automatically.
 
 === Registering and Updating Meters
 Your code