From 723668dfa4197a3576d772a6563ce831a78c3bbb Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Fri, 13 Dec 2024 15:19:45 +0100
Subject: [PATCH 01/13] explain manual instrumentation

---
 content/en/docs/languages/java/api.md         | 16 +++-
 .../docs/zero-code/java/agent/annotations.md  |  2 +-
 content/en/docs/zero-code/java/agent/api.md   | 76 +++++++++++++++++++
 .../java/spring-boot-starter/annotations.md   |  8 ++
 .../zero-code/java/spring-boot-starter/api.md | 68 +++++++++++++++++
 5 files changed, 168 insertions(+), 2 deletions(-)
 create mode 100644 content/en/docs/zero-code/java/agent/api.md
 create mode 100644 content/en/docs/zero-code/java/spring-boot-starter/api.md

diff --git a/content/en/docs/languages/java/api.md b/content/en/docs/languages/java/api.md
index 9d8d4fb4b62c..5ecd2f8aefa7 100644
--- a/content/en/docs/languages/java/api.md
+++ b/content/en/docs/languages/java/api.md
@@ -600,7 +600,7 @@ public class OpenTelemetryUsage {
 ```
 <!-- prettier-ignore-end -->
 
-### GlobalOpenTelemetry
+#### GlobalOpenTelemetry
 
 [GlobalOpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/GlobalOpenTelemetry.html)
 holds a global singleton [OpenTelemetry](#opentelemetry) instance.
@@ -655,6 +655,20 @@ public class GlobalOpenTelemetryUsage {
 ```
 <!-- prettier-ignore-end -->
 
+#### OpenTelemetry in Java Agent
+
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the agent.
+Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
+
+Read more about [extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
+
+#### OpenTelemetry in Spring Boot starter
+
+The Spring Boot starter is a special case where `OpenTelemetry` is available as a
+Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+
+Read more about [extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
+
 ### TracerProvider
 
 [TracerProvider](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/trace/TracerProvider.html)
diff --git a/content/en/docs/zero-code/java/agent/annotations.md b/content/en/docs/zero-code/java/agent/annotations.md
index 65072f1ab965..7f8dc9146492 100644
--- a/content/en/docs/zero-code/java/agent/annotations.md
+++ b/content/en/docs/zero-code/java/agent/annotations.md
@@ -136,5 +136,5 @@ instrumented.
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
 tracer that can be used for
-[Manual Instrumentation](/docs/languages/java/instrumentation/) and execute code
+[Manual Instrumentation](../api) and execute code
 within the scope of that span.
diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
new file mode 100644
index 000000000000..ccc35fe3abe8
--- /dev/null
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -0,0 +1,76 @@
+---
+title: Manual instrumentation
+description:
+  Extending a Java agent with custom manual instrumentation.
+weight: 21
+---
+
+## Introduction
+
+In addition to the out-of-the-box instrumentation, you can extend the Java agent with custom manual instrumentation. 
+This allows you to create [spans](/docs/concepts/signals/traces/#spans) and [metrics](/docs/concepts/signals/metrics) 
+for your own code without doing too many code changes.
+
+## Dependencies
+
+Add a dependency on the `opentelemetry-api` library.
+
+### Maven
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry</groupId>
+    <artifactId>opentelemetry-api</artifactId>
+    <version>{{% param vers.otel %}}</version>
+  </dependency>
+</dependencies>
+```
+
+### Gradle
+
+```groovy
+dependencies {
+    implementation('io.opentelemetry:opentelemetry-api:{{% param vers.otel %}}')
+}
+```
+
+## OpenTelemetry
+
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the agent.
+Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
+
+## Span
+
+{{% alert title="Note" color="info" %}}
+
+For the most common use cases, use the `@WithSpan` annotation instead of manual instrumentation.
+See [Annotations](../annotations) for more information.
+
+{{% /alert %}}
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+Tracer tracer = GlobalOpenTelemetry.getTracer("application");
+```
+
+Use the `Tracer` to create a span as explained in the [Span](/docs/languages/java/api/#span) section.
+
+A full example can be found [example repository].
+
+## Meter
+
+```java
+import io.opentelemetry.api.GlobalOpenTelemetry;
+import io.opentelemetry.api.metrics.Meter;
+
+Meter meter = GlobalOpenTelemetry.getMeter("application");
+```
+
+Use the `Meter` to create a counter, gauge or histogram as explained in the [Meter](/docs/languages/java/api/#meter) section.
+
+A full example can be found [example repository].
+
+[example repository]: https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
index 7b4ef37cf450..4b6c9440cfee 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
@@ -120,3 +120,11 @@ annotation:
 | Name    | Type     | Description    | Default Value         |
 | ------- | -------- | -------------- | --------------------- |
 | `value` | `String` | Attribute name | Method parameter name |
+    
+
+## Next steps
+
+Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
+tracer that can be used for
+[Manual Instrumentation](../api) and execute code
+within the scope of that span.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
new file mode 100644
index 000000000000..744b001aa8b0
--- /dev/null
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -0,0 +1,68 @@
+---
+title: Manual instrumentation
+description:
+  Extending the Spring Boot starter with custom manual instrumentation.
+weight: 21
+---
+
+## Introduction
+
+In addition to the out-of-the-box instrumentation, you can extend the Spring starter with custom manual instrumentation. 
+This allows you to create [spans](/docs/concepts/signals/traces/#spans) and [metrics](/docs/concepts/signals/metrics) 
+for your own code without doing too many code changes.
+
+The required dependencies are already included in the Spring Boot starter.
+
+## OpenTelemetry
+
+The Spring Boot starter is a special case where `OpenTelemetry` is available as a
+Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+
+## Span
+
+{{% alert title="Note" color="info" %}}
+
+For the most common use cases, use the `@WithSpan` annotation instead of manual instrumentation.
+See [Annotations](../annotations) for more information.
+
+{{% /alert %}}
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Tracer;
+
+@Controller
+public class MyController {
+  private final Tracer tracer;
+
+  public MyController(OpenTelemetry openTelemetry) {
+    this.tracer = openTelemetry.getTracer("application");
+  }
+}
+```
+
+Use the `Tracer` to create a span as explained in the [Span](/docs/languages/java/api/#span) section.
+
+A full example can be found [example repository].
+
+## Meter
+
+```java
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.metrics.Meter;
+
+@Controller
+public class MyController {
+  private final Meter meter;
+
+  public MyController(OpenTelemetry openTelemetry) {
+    this.meter = openTelemetry.getMeter("application");
+  }
+}
+```
+
+Use the `Meter` to create a counter, gauge or histogram as explained in the [Meter](/docs/languages/java/api/#meter) section.
+
+A full example can be found [example repository].
+
+[example repository]: https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native

From 4a1224c6dc6b6a22ca76161d5c55fd772f6d6ba6 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Fri, 13 Dec 2024 15:25:46 +0100
Subject: [PATCH 02/13] explain manual instrumentation

---
 content/en/docs/languages/java/api.md         | 15 ++++++----
 .../docs/zero-code/java/agent/annotations.md  |  3 +-
 content/en/docs/zero-code/java/agent/api.md   | 29 +++++++++++--------
 .../java/spring-boot-starter/annotations.md   |  4 +--
 .../zero-code/java/spring-boot-starter/api.md | 25 +++++++++-------
 5 files changed, 43 insertions(+), 33 deletions(-)

diff --git a/content/en/docs/languages/java/api.md b/content/en/docs/languages/java/api.md
index 5ecd2f8aefa7..d693ba04856a 100644
--- a/content/en/docs/languages/java/api.md
+++ b/content/en/docs/languages/java/api.md
@@ -657,17 +657,20 @@ public class GlobalOpenTelemetryUsage {
 
 #### OpenTelemetry in Java Agent
 
-The Java agent is a special case where `GlobalOpenTelemetry` is set by the agent.
-Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the
+agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
+instance.
 
-Read more about [extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
+Read more about
+[extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
 
 #### OpenTelemetry in Spring Boot starter
 
-The Spring Boot starter is a special case where `OpenTelemetry` is available as a
-Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+The Spring Boot starter is a special case where `OpenTelemetry` is available as
+a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
 
-Read more about [extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
+Read more about
+[extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
 
 ### TracerProvider
 
diff --git a/content/en/docs/zero-code/java/agent/annotations.md b/content/en/docs/zero-code/java/agent/annotations.md
index 7f8dc9146492..e2c3c08b2489 100644
--- a/content/en/docs/zero-code/java/agent/annotations.md
+++ b/content/en/docs/zero-code/java/agent/annotations.md
@@ -135,6 +135,5 @@ instrumented.
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for
-[Manual Instrumentation](../api) and execute code
+tracer that can be used for [Manual Instrumentation](../api) and execute code
 within the scope of that span.
diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index ccc35fe3abe8..8dcf09fb6dc0 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,15 +1,16 @@
 ---
 title: Manual instrumentation
-description:
-  Extending a Java agent with custom manual instrumentation.
+description: Extending a Java agent with custom manual instrumentation.
 weight: 21
 ---
 
 ## Introduction
 
-In addition to the out-of-the-box instrumentation, you can extend the Java agent with custom manual instrumentation. 
-This allows you to create [spans](/docs/concepts/signals/traces/#spans) and [metrics](/docs/concepts/signals/metrics) 
-for your own code without doing too many code changes.
+In addition to the out-of-the-box instrumentation, you can extend the Java agent
+with custom manual instrumentation. This allows you to create
+[spans](/docs/concepts/signals/traces/#spans) and
+[metrics](/docs/concepts/signals/metrics) for your own code without doing too
+many code changes.
 
 ## Dependencies
 
@@ -37,15 +38,16 @@ dependencies {
 
 ## OpenTelemetry
 
-The Java agent is a special case where `GlobalOpenTelemetry` is set by the agent.
-Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the
+agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
+instance.
 
 ## Span
 
 {{% alert title="Note" color="info" %}}
 
-For the most common use cases, use the `@WithSpan` annotation instead of manual instrumentation.
-See [Annotations](../annotations) for more information.
+For the most common use cases, use the `@WithSpan` annotation instead of manual
+instrumentation. See [Annotations](../annotations) for more information.
 
 {{% /alert %}}
 
@@ -56,7 +58,8 @@ import io.opentelemetry.api.trace.Tracer;
 Tracer tracer = GlobalOpenTelemetry.getTracer("application");
 ```
 
-Use the `Tracer` to create a span as explained in the [Span](/docs/languages/java/api/#span) section.
+Use the `Tracer` to create a span as explained in the
+[Span](/docs/languages/java/api/#span) section.
 
 A full example can be found [example repository].
 
@@ -69,8 +72,10 @@ import io.opentelemetry.api.metrics.Meter;
 Meter meter = GlobalOpenTelemetry.getMeter("application");
 ```
 
-Use the `Meter` to create a counter, gauge or histogram as explained in the [Meter](/docs/languages/java/api/#meter) section.
+Use the `Meter` to create a counter, gauge or histogram as explained in the
+[Meter](/docs/languages/java/api/#meter) section.
 
 A full example can be found [example repository].
 
-[example repository]: https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent
+[example repository]:
+  https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
index 4b6c9440cfee..bb997ea185cb 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
@@ -120,11 +120,9 @@ annotation:
 | Name    | Type     | Description    | Default Value         |
 | ------- | -------- | -------------- | --------------------- |
 | `value` | `String` | Attribute name | Method parameter name |
-    
 
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for
-[Manual Instrumentation](../api) and execute code
+tracer that can be used for [Manual Instrumentation](../api) and execute code
 within the scope of that span.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index 744b001aa8b0..67702c8c61b2 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -7,23 +7,25 @@ weight: 21
 
 ## Introduction
 
-In addition to the out-of-the-box instrumentation, you can extend the Spring starter with custom manual instrumentation. 
-This allows you to create [spans](/docs/concepts/signals/traces/#spans) and [metrics](/docs/concepts/signals/metrics) 
-for your own code without doing too many code changes.
+In addition to the out-of-the-box instrumentation, you can extend the Spring
+starter with custom manual instrumentation. This allows you to create
+[spans](/docs/concepts/signals/traces/#spans) and
+[metrics](/docs/concepts/signals/metrics) for your own code without doing too
+many code changes.
 
 The required dependencies are already included in the Spring Boot starter.
 
 ## OpenTelemetry
 
-The Spring Boot starter is a special case where `OpenTelemetry` is available as a
-Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+The Spring Boot starter is a special case where `OpenTelemetry` is available as
+a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
 
 ## Span
 
 {{% alert title="Note" color="info" %}}
 
-For the most common use cases, use the `@WithSpan` annotation instead of manual instrumentation.
-See [Annotations](../annotations) for more information.
+For the most common use cases, use the `@WithSpan` annotation instead of manual
+instrumentation. See [Annotations](../annotations) for more information.
 
 {{% /alert %}}
 
@@ -41,7 +43,8 @@ public class MyController {
 }
 ```
 
-Use the `Tracer` to create a span as explained in the [Span](/docs/languages/java/api/#span) section.
+Use the `Tracer` to create a span as explained in the
+[Span](/docs/languages/java/api/#span) section.
 
 A full example can be found [example repository].
 
@@ -61,8 +64,10 @@ public class MyController {
 }
 ```
 
-Use the `Meter` to create a counter, gauge or histogram as explained in the [Meter](/docs/languages/java/api/#meter) section.
+Use the `Meter` to create a counter, gauge or histogram as explained in the
+[Meter](/docs/languages/java/api/#meter) section.
 
 A full example can be found [example repository].
 
-[example repository]: https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native
+[example repository]:
+  https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native

From de10d105612cd0b8312ba4c51c48da1db2fdb2d1 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Fri, 13 Dec 2024 15:33:35 +0100
Subject: [PATCH 03/13] explain manual instrumentation

---
 content/en/docs/languages/java/api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/en/docs/languages/java/api.md b/content/en/docs/languages/java/api.md
index d693ba04856a..2a4c4bc55e9d 100644
--- a/content/en/docs/languages/java/api.md
+++ b/content/en/docs/languages/java/api.md
@@ -655,7 +655,7 @@ public class GlobalOpenTelemetryUsage {
 ```
 <!-- prettier-ignore-end -->
 
-#### OpenTelemetry in Java Agent
+#### OpenTelemetry in Java agent
 
 The Java agent is a special case where `GlobalOpenTelemetry` is set by the
 agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`

From d90c2784e9da9759138ef1f616d93cbb204518dd Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Mon, 16 Dec 2024 11:21:06 +0100
Subject: [PATCH 04/13] Apply suggestions from code review

Co-authored-by: Severin Neumann <severin.neumann@altmuehlnet.de>
---
 content/en/docs/zero-code/java/agent/annotations.md            | 2 +-
 content/en/docs/zero-code/java/agent/api.md                    | 3 ++-
 .../en/docs/zero-code/java/spring-boot-starter/annotations.md  | 2 +-
 content/en/docs/zero-code/java/spring-boot-starter/api.md      | 3 ++-
 4 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/annotations.md b/content/en/docs/zero-code/java/agent/annotations.md
index e2c3c08b2489..3abcb5a62fd1 100644
--- a/content/en/docs/zero-code/java/agent/annotations.md
+++ b/content/en/docs/zero-code/java/agent/annotations.md
@@ -135,5 +135,5 @@ instrumented.
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for [Manual Instrumentation](../api) and execute code
+tracer that can be used for [custom instrumentation](../api) and execute code
 within the scope of that span.
diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index 8dcf09fb6dc0..ac971cfc4327 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,5 +1,6 @@
 ---
-title: Manual instrumentation
+title: Extending with custom manual instrumenation
+linkTitle: Extending instrumentation
 description: Extending a Java agent with custom manual instrumentation.
 weight: 21
 ---
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
index bb997ea185cb..de07c2f4c7e3 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
@@ -124,5 +124,5 @@ annotation:
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for [Manual Instrumentation](../api) and execute code
+tracer that can be used for [custom instrumentation](../api) and execute code
 within the scope of that span.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index 67702c8c61b2..e87f8a0b30e0 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -1,5 +1,6 @@
 ---
-title: Manual instrumentation
+title: Extending with custom manual instrumenation
+linkTitle: Extending instrumentation
 description:
   Extending the Spring Boot starter with custom manual instrumentation.
 weight: 21

From d04ebc919afd2177b3970ae7aaf3f57ba90e0fe5 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Mon, 16 Dec 2024 11:28:41 +0100
Subject: [PATCH 05/13] spelling

---
 content/en/docs/zero-code/java/agent/api.md               | 2 +-
 content/en/docs/zero-code/java/spring-boot-starter/api.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index ac971cfc4327..87fdfe3aa2f2 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,5 +1,5 @@
 ---
-title: Extending with custom manual instrumenation
+title: Extending with custom manual instrumentation
 linkTitle: Extending instrumentation
 description: Extending a Java agent with custom manual instrumentation.
 weight: 21
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index e87f8a0b30e0..4a9f2653ec26 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -1,5 +1,5 @@
 ---
-title: Extending with custom manual instrumenation
+title: Extending with custom manual instrumentation
 linkTitle: Extending instrumentation
 description:
   Extending the Spring Boot starter with custom manual instrumentation.

From e9a51ee20c6b6304f1ffb816bfda736ad7e10478 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Tue, 17 Dec 2024 16:19:06 +0100
Subject: [PATCH 06/13] using API

---
 content/en/docs/zero-code/java/agent/api.md               | 4 ++--
 content/en/docs/zero-code/java/spring-boot-starter/api.md | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index 87fdfe3aa2f2..9ac25934d29d 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,5 +1,5 @@
 ---
-title: Extending with custom manual instrumentation
+title: Extending with custom manual instrumentation using the OpenTelemetry API
 linkTitle: Extending instrumentation
 description: Extending a Java agent with custom manual instrumentation.
 weight: 21
@@ -8,7 +8,7 @@ weight: 21
 ## Introduction
 
 In addition to the out-of-the-box instrumentation, you can extend the Java agent
-with custom manual instrumentation. This allows you to create
+with custom manual instrumentation using the OpenTelemetry API. This allows you to create
 [spans](/docs/concepts/signals/traces/#spans) and
 [metrics](/docs/concepts/signals/metrics) for your own code without doing too
 many code changes.
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index 4a9f2653ec26..cb80e398bfa0 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -1,5 +1,5 @@
 ---
-title: Extending with custom manual instrumentation
+title: Extending with custom manual instrumentation using the OpenTelemetry API
 linkTitle: Extending instrumentation
 description:
   Extending the Spring Boot starter with custom manual instrumentation.
@@ -9,8 +9,8 @@ weight: 21
 ## Introduction
 
 In addition to the out-of-the-box instrumentation, you can extend the Spring
-starter with custom manual instrumentation. This allows you to create
-[spans](/docs/concepts/signals/traces/#spans) and
+starter with custom manual instrumentation using the OpenTelemetry API. 
+This allows you to create [spans](/docs/concepts/signals/traces/#spans) and
 [metrics](/docs/concepts/signals/metrics) for your own code without doing too
 many code changes.
 

From bd1255b0955b679483686f1a420449ddd4de2be9 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Tue, 17 Dec 2024 16:21:23 +0100
Subject: [PATCH 07/13] using API

---
 content/en/docs/zero-code/java/agent/api.md               | 4 ++--
 content/en/docs/zero-code/java/spring-boot-starter/api.md | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index 9ac25934d29d..10126f5e8990 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -8,8 +8,8 @@ weight: 21
 ## Introduction
 
 In addition to the out-of-the-box instrumentation, you can extend the Java agent
-with custom manual instrumentation using the OpenTelemetry API. This allows you to create
-[spans](/docs/concepts/signals/traces/#spans) and
+with custom manual instrumentation using the OpenTelemetry API. This allows you
+to create [spans](/docs/concepts/signals/traces/#spans) and
 [metrics](/docs/concepts/signals/metrics) for your own code without doing too
 many code changes.
 
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index cb80e398bfa0..fc34868a8009 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -9,8 +9,8 @@ weight: 21
 ## Introduction
 
 In addition to the out-of-the-box instrumentation, you can extend the Spring
-starter with custom manual instrumentation using the OpenTelemetry API. 
-This allows you to create [spans](/docs/concepts/signals/traces/#spans) and
+starter with custom manual instrumentation using the OpenTelemetry API. This
+allows you to create [spans](/docs/concepts/signals/traces/#spans) and
 [metrics](/docs/concepts/signals/metrics) for your own code without doing too
 many code changes.
 

From c2e70af6fc829c625d70b03410e07b677c3a3133 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Wed, 18 Dec 2024 12:49:06 +0100
Subject: [PATCH 08/13] Update content/en/docs/zero-code/java/agent/api.md

Co-authored-by: Severin Neumann <severin.neumann@altmuehlnet.de>
---
 content/en/docs/zero-code/java/agent/api.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index 10126f5e8990..c1c31497d807 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,7 +1,7 @@
 ---
-title: Extending with custom manual instrumentation using the OpenTelemetry API
-linkTitle: Extending instrumentation
-description: Extending a Java agent with custom manual instrumentation.
+title: Extending instrumentations with the API
+linkTitle: Extend with the API
+description: Use the OpenTelemetry API in combination with the Java agent to extend the automatically generated telemetry with custom instrumentations
 weight: 21
 ---
 

From ba348bb198af25aba5213b317db20341ac10d1bb Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Wed, 18 Dec 2024 12:54:11 +0100
Subject: [PATCH 09/13] using API

---
 content/en/docs/zero-code/java/agent/api.md               | 2 +-
 content/en/docs/zero-code/java/spring-boot-starter/api.md | 7 +++----
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index c1c31497d807..f7fae4c6a3cd 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,7 +1,7 @@
 ---
 title: Extending instrumentations with the API
 linkTitle: Extend with the API
-description: Use the OpenTelemetry API in combination with the Java agent to extend the automatically generated telemetry with custom instrumentations
+description: Use the OpenTelemetry API in combination with the Java agent to extend the automatically generated telemetry with custom spans and metrics
 weight: 21
 ---
 
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index fc34868a8009..bbffbc33f5ad 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -1,8 +1,7 @@
 ---
-title: Extending with custom manual instrumentation using the OpenTelemetry API
-linkTitle: Extending instrumentation
-description:
-  Extending the Spring Boot starter with custom manual instrumentation.
+title: Extending instrumentations with the API
+linkTitle: Extend with the API
+description: Use the OpenTelemetry API in combination with the Spring Boot starter to extend the automatically generated telemetry with custom spans and metrics
 weight: 21
 ---
 

From 1356d4f94739aa15339bfee5123fcc4660dece2e Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Wed, 18 Dec 2024 12:55:21 +0100
Subject: [PATCH 10/13] using API

---
 content/en/docs/zero-code/java/agent/api.md               | 4 +++-
 content/en/docs/zero-code/java/spring-boot-starter/api.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index f7fae4c6a3cd..e1a37ce8283f 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -1,7 +1,9 @@
 ---
 title: Extending instrumentations with the API
 linkTitle: Extend with the API
-description: Use the OpenTelemetry API in combination with the Java agent to extend the automatically generated telemetry with custom spans and metrics
+description:
+  Use the OpenTelemetry API in combination with the Java agent to extend the
+  automatically generated telemetry with custom spans and metrics
 weight: 21
 ---
 
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index bbffbc33f5ad..e286e4852bf6 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -1,7 +1,9 @@
 ---
 title: Extending instrumentations with the API
 linkTitle: Extend with the API
-description: Use the OpenTelemetry API in combination with the Spring Boot starter to extend the automatically generated telemetry with custom spans and metrics
+description:
+  Use the OpenTelemetry API in combination with the Spring Boot starter to
+  extend the automatically generated telemetry with custom spans and metrics
 weight: 21
 ---
 

From 217dc463c11ea694fb46d5ed8f07a9b8d3a3d0f6 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Mon, 6 Jan 2025 11:55:02 +0100
Subject: [PATCH 11/13] Apply suggestions from code review

Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
---
 content/en/docs/zero-code/java/agent/annotations.md           | 3 +--
 content/en/docs/zero-code/java/agent/api.md                   | 4 ++--
 .../en/docs/zero-code/java/spring-boot-starter/annotations.md | 3 +--
 content/en/docs/zero-code/java/spring-boot-starter/api.md     | 4 ++--
 4 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/content/en/docs/zero-code/java/agent/annotations.md b/content/en/docs/zero-code/java/agent/annotations.md
index 3abcb5a62fd1..740b4f81d585 100644
--- a/content/en/docs/zero-code/java/agent/annotations.md
+++ b/content/en/docs/zero-code/java/agent/annotations.md
@@ -135,5 +135,4 @@ instrumented.
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for [custom instrumentation](../api) and execute code
-within the scope of that span.
+tracer that can be used for [custom instrumentation](../api).
diff --git a/content/en/docs/zero-code/java/agent/api.md b/content/en/docs/zero-code/java/agent/api.md
index e1a37ce8283f..3ef07fb7d3df 100644
--- a/content/en/docs/zero-code/java/agent/api.md
+++ b/content/en/docs/zero-code/java/agent/api.md
@@ -64,7 +64,7 @@ Tracer tracer = GlobalOpenTelemetry.getTracer("application");
 Use the `Tracer` to create a span as explained in the
 [Span](/docs/languages/java/api/#span) section.
 
-A full example can be found [example repository].
+A full example can be found in the [example repository].
 
 ## Meter
 
@@ -78,7 +78,7 @@ Meter meter = GlobalOpenTelemetry.getMeter("application");
 Use the `Meter` to create a counter, gauge or histogram as explained in the
 [Meter](/docs/languages/java/api/#meter) section.
 
-A full example can be found [example repository].
+A full example can be found in the [example repository].
 
 [example repository]:
   https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
index de07c2f4c7e3..647386a2c8cd 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md
@@ -124,5 +124,4 @@ annotation:
 ## Next steps
 
 Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
-tracer that can be used for [custom instrumentation](../api) and execute code
-within the scope of that span.
+tracer that can be used [custom instrumentation](../api).
diff --git a/content/en/docs/zero-code/java/spring-boot-starter/api.md b/content/en/docs/zero-code/java/spring-boot-starter/api.md
index e286e4852bf6..8fcc63452b8f 100644
--- a/content/en/docs/zero-code/java/spring-boot-starter/api.md
+++ b/content/en/docs/zero-code/java/spring-boot-starter/api.md
@@ -48,7 +48,7 @@ public class MyController {
 Use the `Tracer` to create a span as explained in the
 [Span](/docs/languages/java/api/#span) section.
 
-A full example can be found [example repository].
+A full example can be found in the [example repository].
 
 ## Meter
 
@@ -69,7 +69,7 @@ public class MyController {
 Use the `Meter` to create a counter, gauge or histogram as explained in the
 [Meter](/docs/languages/java/api/#meter) section.
 
-A full example can be found [example repository].
+A full example can be found in the [example repository].
 
 [example repository]:
   https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native

From 7dd6e4496109ba45ca7967a95d8d756230ba127b Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Fri, 10 Jan 2025 10:26:55 +0100
Subject: [PATCH 12/13] use info boxes

---
 content/en/docs/languages/java/api.md | 37 ++++++++++++++-------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/content/en/docs/languages/java/api.md b/content/en/docs/languages/java/api.md
index 2a4c4bc55e9d..f60edc3d6904 100644
--- a/content/en/docs/languages/java/api.md
+++ b/content/en/docs/languages/java/api.md
@@ -560,6 +560,14 @@ public class AttributesUsage {
 
 ### OpenTelemetry
 
+{{% alert title="Spring Boot Starter" %}} 
+The Spring Boot starter is a special case where `OpenTelemetry` is available as
+a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+
+Read more about
+[extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
+{{% /alert %}}
+
 [OpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/OpenTelemetry.html)
 is a holder for top-level API components which is convenient to pass to
 instrumentation.
@@ -600,7 +608,17 @@ public class OpenTelemetryUsage {
 ```
 <!-- prettier-ignore-end -->
 
-#### GlobalOpenTelemetry
+### GlobalOpenTelemetry
+
+
+{{% alert title="Java agent" %}} 
+The Java agent is a special case where `GlobalOpenTelemetry` is set by the
+agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
+instance.
+
+Read more about
+[extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
+{{% /alert %}}
 
 [GlobalOpenTelemetry](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/GlobalOpenTelemetry.html)
 holds a global singleton [OpenTelemetry](#opentelemetry) instance.
@@ -655,23 +673,6 @@ public class GlobalOpenTelemetryUsage {
 ```
 <!-- prettier-ignore-end -->
 
-#### OpenTelemetry in Java agent
-
-The Java agent is a special case where `GlobalOpenTelemetry` is set by the
-agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
-instance.
-
-Read more about
-[extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).
-
-#### OpenTelemetry in Spring Boot starter
-
-The Spring Boot starter is a special case where `OpenTelemetry` is available as
-a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
-
-Read more about
-[extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
-
 ### TracerProvider
 
 [TracerProvider](https://www.javadoc.io/doc/io.opentelemetry/opentelemetry-api/latest/io/opentelemetry/api/trace/TracerProvider.html)

From 775205305d4dcafedd9dda52e4b56bc437ecfe53 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Fri, 10 Jan 2025 10:30:23 +0100
Subject: [PATCH 13/13] use info boxes

---
 content/en/docs/languages/java/api.md | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/content/en/docs/languages/java/api.md b/content/en/docs/languages/java/api.md
index f60edc3d6904..bbe415fab278 100644
--- a/content/en/docs/languages/java/api.md
+++ b/content/en/docs/languages/java/api.md
@@ -560,9 +560,9 @@ public class AttributesUsage {
 
 ### OpenTelemetry
 
-{{% alert title="Spring Boot Starter" %}} 
-The Spring Boot starter is a special case where `OpenTelemetry` is available as
-a Spring bean. Simply inject `OpenTelemetry` into your Spring components.
+{{% alert title="Spring Boot Starter" %}} The Spring Boot starter is a special
+case where `OpenTelemetry` is available as a Spring bean. Simply inject
+`OpenTelemetry` into your Spring components.
 
 Read more about
 [extending the Spring Boot starter with custom manual instrumentation](/docs/zero-code/java/spring-boot-starter/api/).
@@ -610,11 +610,9 @@ public class OpenTelemetryUsage {
 
 ### GlobalOpenTelemetry
 
-
-{{% alert title="Java agent" %}} 
-The Java agent is a special case where `GlobalOpenTelemetry` is set by the
-agent. Simply call `GlobalOpenTelemetry.get()` to access the `OpenTelemetry`
-instance.
+{{% alert title="Java agent" %}} The Java agent is a special case where
+`GlobalOpenTelemetry` is set by the agent. Simply call
+`GlobalOpenTelemetry.get()` to access the `OpenTelemetry` instance.
 
 Read more about
 [extending the Java agent with custom manual instrumentation](/docs/zero-code/java/agent/api/).