Small updates to the java agent zero code docs (#5857)

content/en/blog/2024/fuzzing-audit-results.md

@@ -5,7 +5,7 @@ date: 2024-12-20
 author: '[Adam Korczynski](https://github.com/AdamKorcz)'
 issue: 5798
 sig: GC
-cSpell:ignore: Korczynski containerd
+cSpell:ignore: containerd Korczynski
 ---
 
 OpenTelemetry is happy to announce the completion of the Collector's fuzzing

content/en/docs/zero-code/java/agent/annotations.md

@@ -7,17 +7,18 @@ cSpell:ignore: Flowable javac reactivestreams reactivex
 ---
 
 For most users, the out-of-the-box instrumentation is completely sufficient and
-nothing more has to be done. Sometimes, however, users wish to create
+nothing more needs to be done. Sometimes, however, users wish to create
 [spans](/docs/concepts/signals/traces/#spans) for their own custom code without
-doing too much code change.
+having to change much code. The `WithSpan` and `WithAttribute` annotations
+support those use cases.
 
 ## Dependencies
 
 You'll need to add a dependency on the
 `opentelemetry-instrumentation-annotations` library to use the `@WithSpan`
 annotation.
 
-### Maven
+{{< tabpane text=true >}} {{% tab "Maven" %}}
 
 ```xml
 <dependencies>
@@ -29,6 +30,8 @@ annotation.
 </dependencies>
 ```
 
+{{% /tab %}} {{% tab "Gradle" %}}
+
 ### Gradle
 
 ```groovy
@@ -37,10 +40,12 @@ dependencies {
 }
 ```
 
+{{% /tab %}} {{< /tabpane >}}
+
 ## Creating spans around methods with `@WithSpan`
 
-To create a [span](/docs/concepts/signals/traces/#spans) corresponding to one of
-your method, annotate the method with `@WithSpan`.
+To create a [span](/docs/concepts/signals/traces/#spans) that instruments a
+particular method, annotate the method with `@WithSpan`.
 
 ```java
 import io.opentelemetry.instrumentation.annotations.WithSpan;
@@ -78,9 +83,10 @@ types listed below, then the span will not be ended until the future completes.
 ## Adding attributes to the span with `@SpanAttribute`
 
 When a [span](/docs/concepts/signals/traces/#spans) is created for an annotated
-method the values of the arguments to the method invocation can be automatically
-added as [attributes](/docs/concepts/signals/traces/#attributes) to the created
-span by annotating the method parameters with the `@SpanAttribute` annotation.
+method, the values of the arguments to the method invocation can be
+automatically added as [attributes](/docs/concepts/signals/traces/#attributes)
+to the created span. Simply annotate the method parameters with the
+`@SpanAttribute` annotation:
 
 ```java
 import io.opentelemetry.instrumentation.annotations.SpanAttribute;

content/en/docs/zero-code/java/agent/configuration.md

@@ -21,24 +21,24 @@ The agent can consume configuration from one or more of the following sources
 
 ## Configuring with Environment Variables
 
-In some environments, configuring via Environment Variables is more preferred.
-Any setting configurable with a System Property can also be configured with an
-Environment Variable. Many settings below include both options, but where they
-don't apply the following steps to determine the correct name mapping of the
-desired System Property:
+In certain environments, configuring settings through environment variables is
+often preferred. Any setting that can be configured using a system property can
+also be set using an environment variable. While many of the settings below
+provide examples for both formats, for those that do not, use the following
+steps to determine the correct name mapping for the desired system property:
 
-- Convert the System Property to uppercase.
+- Convert the system property name to uppercase.
 - Replace all `.` and `-` characters with `_`.
 
 For example `otel.instrumentation.common.default-enabled` would convert to
 `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`.
 
 ## Configuration file
 
-You can provide a path to agent configuration file by setting the following
+You can provide a path to an agent configuration file by setting the following
 property:
 
-{{% config_option name="otel.javaagent.configuration-file" %}} Path to valid
+{{% config_option name="otel.javaagent.configuration-file" %}} Path to a valid
 Java properties file which contains the agent configuration.
 {{% /config_option %}}
 

content/en/docs/zero-code/java/agent/disable.md

@@ -26,10 +26,11 @@ to have more control of which instrumentation is applied.
 {{% config_option name="otel.instrumentation.[name].enabled" %}} Set to `true`
 to enable each desired instrumentation individually. {{% /config_option %}}
 
-> **Note**: Some instrumentation relies on other instrumentation to function
-> properly. When selectively enabling instrumentation, be sure to enable the
-> transitive dependencies too. Determining this dependency relationship is left
-> as an exercise to the user.
+{{% alert title="Note" color="warning" %}} Some instrumentation relies on other
+instrumentation to function properly. When selectively enabling instrumentation,
+be sure to enable the transitive dependencies too. Determining this dependency
+relationship is left as an exercise to the user. This is considered advanced
+usage and is not recommended for most users. {{% /alert %}}
 
 ## Enable manual instrumentation only
 

content/en/docs/zero-code/java/agent/instrumentation/http.md

@@ -39,9 +39,10 @@ instrumentations.
 
 ## Capturing servlet request parameters
 
-You can configure the agent to capture predefined HTTP request parameter as span
-attributes for requests that are handled by Servlet API. Use the following
-property to define which servlet request parameters you want to capture:
+You can configure the agent to capture predefined HTTP request parameters as
+span attributes for requests that are handled by the Servlet API. Use the
+following property to define which servlet request parameters you want to
+capture:
 
 {{% config_option name="otel.instrumentation.servlet.experimental.capture-request-parameters" %}}
 A comma-separated list of request parameter names. {{% /config_option %}}