Rework of What-is-OTel and Instrumentation pages

Author: chalin

content/en/docs/concepts/instrumentation/_index.md

@@ -5,16 +5,15 @@ aliases: [instrumenting]
 weight: 15
 ---
 
-In order to make a system observable, it must be **instrumented**: That is, code
-from the system's components must emit [traces](/docs/concepts/signals/traces/),
-[metrics](/docs/concepts/signals/metrics/), and
-[logs](/docs/concepts/signals/logs/).
+For a system [observable], it must be **instrumented**: that is, code from the
+system's components must emit [signals], such as [traces], [metrics], and
+[logs].
 
 Using OpenTelemetry, you can instrument your code in two primary ways:
 
-1. [Code-based solutions](/docs/concepts/instrumentation/code-based) via
-   official [APIs and SDKs for most languages](/docs/languages/)
-2. [Zero-code solutions](/docs/concepts/instrumentation/zero-code/)
+1. [Code-based solutions](code-based/) via official
+   [APIs and SDKs for most languages](/docs/languages/)
+2. [Zero-code solutions](zero-code/)
 
 **Code-based** solutions allow you to get deeper insight and rich telemetry from
 your application itself. They let you use the OpenTelemetry API to generate
@@ -37,20 +36,24 @@ solutions. The following things are also a part of OpenTelemetry:
 - Libraries can leverage the OpenTelemetry API as a dependency, which will have
   no impact on applications using that library, unless the OpenTelemetry SDK is
   imported.
-- For each [signal](/docs/concepts/signals) (traces, metrics, logs) you have
-  several methods at your disposals to create, process, and export them.
-- With [context propagation](/docs/concepts/context-propagation) built into the
+- For each of the [signals] you have several methods at your disposals to
+  create, process, and export them.
+- With [context propagation](../context-propagation/) built into the
   implementations, you can correlate signals regardless of where they are
   generated.
-- [Resources](/docs/concepts/resources) and
-  [Instrumentation Scopes](/docs/concepts/instrumentation-scope) allow grouping
-  of signals, by different entities, like, the
-  [host](/docs/specs/semconv/resource/host/),
+- [Resources](../resources/) and
+  [Instrumentation Scopes](../instrumentation-scope/) allow grouping of signals,
+  by different entities, like, the [host](/docs/specs/semconv/resource/host/),
   [operating system](/docs/specs/semconv/resource/os/) or
   [K8s cluster](/docs/specs/semconv/resource/k8s/#cluster)
 - Each language-specific implementation of the API and SDK follows the
   requirements and expectations of the
   [OpenTelemetry specification](/docs/specs/otel/).
-- [Semantic Conventions](/docs/concepts/semantic-conventions) provide a common
-  naming schema that can be used for standardization across code bases and
-  platforms.
+- [Semantic Conventions](../semantic-conventions/) provide a common naming
+  schema that can be used for standardization across code bases and platforms.
+
+[logs]: ../signals/traces/
+[metrics]: ../signals/traces/
+[observable]: ../observability-primer/#what-is-observability
+[signals]: ../signals/
+[traces]: ../signals/traces/

content/en/docs/what-is-opentelemetry.md

@@ -1,50 +1,49 @@
 ---
 title: What is OpenTelemetry?
-description: A short explanation of what OpenTelemetry is and isn't.
+description: A brief explanation of what OpenTelemetry is and isn't.
 aliases: [/about, /docs/concepts/what-is-opentelemetry, /otel]
 weight: 150
 ---
 
 OpenTelemetry is:
 
-- An [Observability](/docs/concepts/observability-primer/#what-is-observability)
-  framework and toolkit designed to create and manage telemetry data such as
-  [traces](/docs/concepts/signals/traces/),
-  [metrics](/docs/concepts/signals/metrics/), and
-  [logs](/docs/concepts/signals/logs/).
-- Vendor- and tool-agnostic, meaning that it can be used with a broad variety of
-  Observability backends, including open source tools like
-  [Jaeger](https://www.jaegertracing.io/) and
-  [Prometheus](https://prometheus.io/), as well as commercial offerings.
-- Not an observability backend like Jaeger, Prometheus, or other commercial
-  vendors.
-- Focused on the generation, collection, management, and export of telemetry. A
-  major goal of OpenTelemetry is that you can easily instrument your
-  applications or systems, no matter their language, infrastructure, or runtime
-  environment. The storage and visualization of telemetry is intentionally left
-  to other tools.
+- An **[observability] framework and toolkit** designed to facilitate the
+
+  - Generation
+  - Export
+  - Collection
+
+  of [telemetry data][] such as [traces], [metrics], and [logs].
+
+- **Open source** and **vendor- and tool-agnostic**, meaning that it can be used
+  with a broad variety of observability backends, including open source tools
+  like [Jaeger] and [Prometheus], as well as commercial offerings. OpenTelemetry
+  is **not** an observability backend itself.
+
+A major goal of OpenTelemetry is to enable easy instrumentation of your
+applications and systems, regardless of the programming language,
+infrastructure, and runtime environments used.
+
+The (backend) **storage** and (frontend) **visualization** of telemetry data are
+intentionally left to other tools.
 
 ## What is observability?
 
-[Observability](/docs/concepts/observability-primer/#what-is-observability) is
-the ability to understand the internal state of a system by examining its
-outputs. In the context of software, this means being able to understand the
-internal state of a system by examining its telemetry data, which includes
-traces, metrics, and logs.
+[Observability] is the ability to understand the internal state of a system by
+examining its outputs. In the context of software, this means being able to
+understand the internal state of a system by examining its telemetry data, which
+includes traces, metrics, and logs.
 
 To make a system observable, it must be
-[instrumented](/docs/concepts/instrumentation). That is, the code must emit
-[traces](/docs/concepts/signals/traces/),
-[metrics](/docs/concepts/signals/metrics/), or
-[logs](/docs/concepts/signals/logs/). The instrumented data must then be sent to
-an observability backend.
+[instrumented](../concepts/instrumentation). That is, the code must emit
+[traces], [metrics], or [logs]. The instrumented data must then be sent to an
+observability backend.
 
 ## Why OpenTelemetry?
 
 With the rise of cloud computing, microservices architectures, and increasingly
 complex business requirements, the need for software and infrastructure
-[observability](/docs/concepts/observability-primer/#what-is-observability) is
-greater than ever.
+[observability] is greater than ever.
 
 OpenTelemetry satisfies the need for observability while following two key
 principles:
@@ -62,24 +61,23 @@ If you want to learn more, take a look at OpenTelemetry's
 
 OpenTelemetry consists of the following major components:
 
-- A [specification](/docs/specs/otel) for all components
-- A standard [protocol](/docs/specs/otlp/) that defines the shape of telemetry
-  data
-- [Semantic conventions](/docs/specs/semconv/) that define a standard naming
-  scheme for common telemetry data types
+- A [specification](../specs/otel) for all components
+- A standard [protocol](../specs/otlp/) that defines the shape of telemetry data
+- [Semantic conventions](../specs/semconv/) that define a standard naming scheme
+  for common telemetry data types
 - APIs that define how to generate telemetry data
-- [Language SDKs](/docs/languages) that implement the specification, APIs, and
+- [Language SDKs](../languages) that implement the specification, APIs, and
   export of telemetry data
 - A [library ecosystem](/ecosystem/registry) that implements instrumentation for
   common libraries and frameworks
 - Automatic instrumentation components that generate telemetry data without
   requiring code changes
-- The [OpenTelemetry Collector](/docs/collector), a proxy that receives,
-  processes, and exports telemetry data
+- The [OpenTelemetry Collector](../collector), a proxy that receives, processes,
+  and exports telemetry data
 - Various other tools, such as the
-  [OpenTelemetry Operator for Kubernetes](/docs/platforms/kubernetes/operator/),
-  [OpenTelemetry Helm Charts](/docs/platforms/kubernetes/helm/), and
-  [community assets for FaaS](/docs/platforms/faas/)
+  [OpenTelemetry Operator for Kubernetes](../platforms/kubernetes/operator/),
+  [OpenTelemetry Helm Charts](../platforms/kubernetes/helm/), and
+  [community assets for FaaS](../platforms/faas/)
 
 OpenTelemetry is used by a wide variety of
 [libraries, services and apps](/ecosystem/integrations/) that have OpenTelemetry
@@ -97,7 +95,7 @@ extended include:
 - Adding a receiver to the OpenTelemetry Collector to support telemetry data
   from a custom source
 - Loading custom instrumentation libraries into an SDK
-- Creating a [distribution](/docs/concepts/distributions/) of an SDK or the
+- Creating a [distribution](../concepts/distributions/) of an SDK or the
   Collector tailored to a specific use case
 - Creating a new exporter for a custom backend that doesn't yet support the
   OpenTelemetry protocol (OTLP)
@@ -108,8 +106,7 @@ designed to make it possible at nearly every level.
 
 ## History
 
-OpenTelemetry is a
-[Cloud Native Computing Foundation (CNCF)](https://www.cncf.io) project that is
+OpenTelemetry is a [Cloud Native Computing Foundation][] (CNCF) project that is
 the result of a [merger] between two prior projects,
 [OpenTracing](https://opentracing.io) and [OpenCensus](https://opencensus.io).
 Both of these projects were created to solve the same problem: the lack of a
@@ -119,12 +116,21 @@ they merged to form OpenTelemetry and combine their strengths while offering a
 single solution.
 
 If you are currently using OpenTracing or OpenCensus, you can learn how to
-migrate to OpenTelemetry in the [Migration guide](/docs/migration/).
+migrate to OpenTelemetry in the [Migration guide](../migration/).
 
 [merger]:
   https://www.cncf.io/blog/2019/05/21/a-brief-history-of-opentelemetry-so-far/
 
 ## What next?
 
-- [Getting started](/docs/getting-started/) — jump right in!
-- Learn about [OpenTelemetry concepts](/docs/concepts/).
+- [Getting started](../getting-started/) — jump right in!
+- Learn about [OpenTelemetry concepts](../concepts/).
+
+[logs]: ../concepts/signals/logs/
+[metrics]: ../concepts/signals/metrics/
+[observability]: ../concepts/observability-primer/#what-is-observability
+[telemetry data]: ../concepts/signals/
+[traces]: ../concepts/signals/traces/
+[Jaeger]: https://www.jaegertracing.io/
+[Prometheus]: https://prometheus.io/
+[Cloud Native Computing Foundation]: https://www.cncf.io