add intro for manual instrumentation labs

tutorial/content/intro/overview_of_otel/index.md

@@ -67,20 +67,13 @@ The implementation of a signal consists of two parts:
 
 <!-- auto and manual instrumentation -->
 Generally speaking, we use the OpenTelemetry API to add instrumentation to our source code.
-In practice, instrumentation can be achieved in various ways, such as:
-- manual instrumentation
-  - requires modification of the source code
-  - allows fine-grained control over what and how telemetry gets generated
-- auto-instrumentation (if available) and library instrumentation to avoid code changes
-  - can be used to get started quickly with observability
-  - collects predefined metrics, traces and logs within a library or framework
-  - added after the fact by injecting an agent (or already included inside the library or framework)
-  - requires close to zero code changes
-- and native instrumentation (already instrumented with OpenTelemetry)
-
-We'll look at them later in more detail.
+In practice, this can be achieved in various ways, such as:
+- manual instrumentation (for fine-grained control)
+- auto-instrumentation and instrumentation libraries (if available and to avoid code changes)
+- by using code that has already been instrumented with OpenTelemetry
+
 <!-- API / SDK separation -->
-For now, let's focus on why OpenTelemetry decided to separate the API from the SDK.
+For now, let's skip futher details an focus on why OpenTelemetry decided to separate the API from the SDK.
 On startup, the application registers a provider for every type of signal.
 After that, calls to the API are forwarded to the respective provider.
 If we don't explicitly register one, OpenTelemetry will use a fallback provider that translates API calls into no-ops.

tutorial/content/labs/instrumentation/automatic/_index.md

@@ -22,3 +22,8 @@ Recognizing these burdens, OpenTelemetry tries to simplify the user experience
 For example, it is designed to integrate well with pre-existing solutions and allows for incremental migration strategies.
 This section explores the mechanisms OpenTelemetry provides for producing telemetry with zero code changes.
 This is where instrumentation libraries and auto-instrumentation come in.
+
+  - can be used to get started quickly with observability
+  - collects predefined metrics, traces and logs within a library or framework
+  - added after the fact by injecting an agent (or already included inside the library or framework)
+  - requires close to zero code changes

tutorial/content/labs/instrumentation/manual/_index.md

@@ -5,10 +5,26 @@ draft = false
 weight = 1
 +++
 
-<!-- Welcome to the first lab!
-This lab looks at how to manually instrument an application by directly using OpenTelemetry's API and SDK.
-In doing so, we explore how each signal works.
-Thereby, we hope you gain an understanding of the fundamental concepts and terminology used by OpenTelemetry. -->
+Welcome to the lab on manual instrumentation!
+Let's look at how to instrument an application by directly using API and SDK packages provided by OpenTelemetry.
+In other words, manual instrumentation requires you to make modifications to the source code.
+This comes with its fair share of benefits and disadvantages.
+The biggest disadvantage is that if you are just starting out, writing manual instrumentation can be daunting because you:
+- need to get familiar with OpenTelemetry packages
+- must be willing to explore how telemetry signals work under the hood
+
+It's totally reasonable to think that this is asking too much of the developers in your organization.
+Another downside could be that you don't want to add observability instrumentation to your code base.
+If that's the case, don't worry; there are other options to generate and emit telemetry.
+We'll look at them in later chapters.
+
+However, there are also reasons for using manual instrumentation:
+- some languages do not support auto-instrumentation
+- provides fine-grained control over what and how telemetry gets generated
+- you want to make observability part of the development process
+- you are a library author or maintainer who wants to offer native instrumentation to your users
+
+So let's get started.
 
 <!-- 
 However, it comes with its own set of trade-offs. 
@@ -23,4 +39,5 @@ Additionally, it is important to consider that alternative implementations might
 This implies that while the SDK provides a robust framework for observability, it may not be the most optimized solution for every scenario. 
 It is essential to weigh these trade-offs against the benefits of OpenTelemetry to determine if it is the right fit for a particular application or organization. 
 But if OpenTelemetry is used in the right way and configured well - the benefits might
--->
+-->
+

tutorial/content/labs/instrumentation/manual/metrics/index.md

@@ -11,8 +11,6 @@ A `MetricReader` in OpenTelemetry is an interface that defines how to read metri
 
 The metric data model in OpenTelemetry defines the structure of the data that is collected and exported by the SDK. It includes information about the resource, instrumentation library, and the actual metrics data. Here's an example of what the metric data model might look like in JSON format:
 
-The lab environment is deliberately designed to be as minimal as possible. It aims to teach fundamental concepts of OpenTelemetry over providing a highly a realistic deployment scenario.
-
 ### How to perform the exercise
 * You need to either start the [repository](https://github.com/JenSeReal/otel-getting-started/) with Codespaces, Gitpod or clone the repository with git and run it locally with dev containers or docker compose
 * Initial directory: `labs/manual-instrumentation-metrics/initial`

tutorial/content/labs/instrumentation/manual/traces/index.md

@@ -5,19 +5,6 @@ draft: false
 weight: 2
 ---
 
-<!-- TODO -->
-<!--
-insert images
-    images/codespaces.PNG
-    vscode_reopen_in_container.png
-
-explain context API
-
-resourcedetector
--->
-
-The lab environment is deliberately designed to be as minimal as possible. It aims to teach fundamental concepts of OpenTelemetry over providing a highly a realistic deployment scenario.
-
 ### How to perform the exercise
 * You need to either start the [repository](https://github.com/JenSeReal/otel-getting-started/) with Codespaces, Gitpod or clone the repository with git and run it locally with dev containers or docker compose
 * Initial directory: `labs/manual-instrumentation-traces/initial`