fix(collector/quick-start): clarify demo scope, explain ports, improve prerequisites (#9622)

Co-authored-by: otelbot <197425009+otelbot@users.noreply.github.com>
Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com>
Co-authored-by: Pablo Baeyens <pbaeyens31+github@gmail.com>

Author: 4 people

content/en/docs/collector/quick-start.md

@@ -1,96 +1,108 @@
 ---
 title: Quick start
-description: Setup and collect telemetry in minutes!
+description: Set up and collect telemetry in minutes!
 aliases: [getting-started]
 weight: 1
 cSpell:ignore: docker dokey gobin okey telemetrygen
 ---
 
 <!-- markdownlint-disable ol-prefix blanks-around-fences -->
 
-The OpenTelemetry Collector receives [traces](/docs/concepts/signals/traces/),
+The OpenTelemetry Collector receives telemetry such as
+[traces](/docs/concepts/signals/traces/),
 [metrics](/docs/concepts/signals/metrics/), and
-[logs](/docs/concepts/signals/logs/), processes the telemetry, and exports it to
-a wide variety of observability backends using its components. For a conceptual
-overview of the Collector, see [Collector](/docs/collector).
+[logs](/docs/concepts/signals/logs/), processes it, and forwards it to one or
+more observability backends through its component pipeline.
 
-You are going to learn to do the following in less than five minutes:
+> [!NOTE]
+>
+> This quick start demo creates a basic local setup. The goal is to show you how
+> the Collector works, not to set up a production-ready environment.
 
-- Set up and run the OpenTelemetry Collector.
-- Send telemetry and see it processed by the Collector.
+In this guide, you will:
+
+- Start a local instance of the OpenTelemetry Collector
+- Generate trace data and send it to the Collector
+- Check that the Collector receives and processes the data
+
+By the end, you will have a simple pipeline running on your machine and a
+clearer idea of how the Collector fits into an observability stack. If you want
+more context before getting started, see the [Collector](/docs/collector)
+overview.
 
 ## Prerequisites
 
-Make sure that your developer environment has the following. This page assumes
-that you're using `bash`. Adapt configuration and commands as necessary for your
-preferred shell.
+Before you begin, make sure your environment has the following tools installed:
+
+- [Docker](https://www.docker.com/) or any compatible container runtime — used
+  to run the Collector
+- [Go](https://go.dev/), one of the latest two minor versions — used to install
+  the telemetry generator
+- [`GOBIN` environment variable][gobin] set — ensures installed Go binaries are
+  available in your PATH[^1]
 
-- [Docker](https://www.docker.com/) or any compatible containers' runtime.
-- [Go](https://go.dev/) 1.20 or higher
-- [`GOBIN` environment variable][gobin] is set; if unset, initialize it
-  appropriately, for example[^1]:
-  ```sh
-  export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
-  ```
+If `GOBIN` isn't set, run:
+
+```sh
+export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
+```
+
+This guide uses `bash` commands. If you're using a different shell, you might
+need to adjust the command syntax.
 
 [^1]:
     For more information, see
     [Your first program](https://go.dev/doc/code#Command).
 
 ## Set up the environment
 
-1. Pull in the OpenTelemetry Collector core Docker image:
+1. Pull the Docker image of the OpenTelemetry Collector core
+   [distribution](/docs/collector/distributions/):
 
    ```sh
    docker pull otel/opentelemetry-collector:{{% param vers %}}
    ```
 
-2. Install the [telemetrygen][] utility:
+2. Install [telemetrygen][], which we'll use to simulate a client that generates
+   telemetry:
 
    ```sh
    go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
    ```
 
-   This utility can simulate a client generating [traces][], [metrics][], and
-   [logs][].
-
 ## Generate and collect telemetry
 
-3. Launch the Collector, listening on ports 4317 (for OTLP gRPC), 4318 (for OTLP
-   HTTP) and 55679 (for ZPages):
+3. Start the Collector:
 
    ```sh
    docker run \
      -p 127.0.0.1:4317:4317 \
      -p 127.0.0.1:4318:4318 \
      -p 127.0.0.1:55679:55679 \
      otel/opentelemetry-collector:{{% param vers %}} \
-     2>&1 | tee collector-output.txt # Optionally tee output for easier search later
+     2>&1 | tee collector-output.txt
    ```
 
-4. In a separate terminal window, generate a few sample traces:
+   The previous command runs the Collector locally and opens three ports:
+   - `4317` — OTLP over gRPC, the default for most SDKs
+   - `4318` — OTLP over HTTP, for clients that don't support gRPC
+   - `55679` — ZPages, a built-in debug UI you can open in the browser
+
+4. In a separate terminal, generate some traces:
 
    ```sh
    $GOBIN/telemetrygen traces --otlp-insecure --traces 3
    ```
 
-   Among the output generated by the utility, you should see a confirmation that
-   traces were generated:
+   You see output confirming the traces were sent:
 
    ```text
    2024-01-16T14:33:15.692-0500  INFO  traces/worker.go:99  traces generated  {"worker": 0, "traces": 3}
    2024-01-16T14:33:15.692-0500  INFO  traces/traces.go:58  stop the batch span processor
    ```
 
-   For an easier time seeing relevant output you can filter it:
-
-   ```sh
-   $GOBIN/telemetrygen traces --otlp-insecure \
-     --traces 3 2>&1 | grep -E 'start|traces|stop'
-   ```
-
-5. In the terminal window running the Collector container, you should see trace
-   ingest activity similar to what is shown in the following example:
+5. Back in the Collector terminal, you should see trace ingest activity similar
+   to the following:
 
    ```console
    $ grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txt
@@ -117,30 +129,27 @@ preferred shell.
    ...
    ```
 
-6. Open <http://localhost:55679/debug/tracez> and select one of the samples in
-   the table to see the traces you've just generated.
+6. To explore the traces visually, open <http://localhost:55679/debug/tracez> in
+   your browser and select one of the traces from the table.
 
-7. After you are done, shutdown the Collector container, for example, using
-   <kbd>Control-C</kbd>.
+7. Press <kbd>Control-C</kbd> to stop the Collector.
 
 ## Next steps
 
-In this tutorial you've started the OpenTelemetry Collector and sent telemetry
-to it. As next steps, consider doing the following:
+At this point, you've run the Collector locally and seen how it handles
+telemetry end to end. From here, you can start learning how it's used in real
+setups:
 
-- Explore different ways to [install the Collector](/docs/collector/install/).
-- Learn about the different modes of the Collector in
-  [Deployment Methods](/docs/collector/deploy/).
-- Familiarize yourself with the Collector
-  [configuration](/docs/collector/configuration) files and structure.
-- Explore available components in the
-  [registry](/ecosystem/registry/?language=collector).
-- Learn how to
-  [build a custom Collector with the OpenTelemetry Collector Builder (OCB)](/docs/collector/extend/ocb/).
+- [Configuration](/docs/collector/configuration): Learn how the Collector's
+  config file works and how to connect it to a real backend like Jaeger or
+  Prometheus.
+- [Deployment patterns](/docs/collector/deploy/): Understand the difference
+  between running the Collector as an agent versus a gateway.
+- [Install the Collector](/docs/collector/install/): Explore installation
+  options beyond Docker, including binaries and Kubernetes.
+- [Component registry](/ecosystem/registry/?language=collector): Browse
+  available receivers, processors, and exporters to extend your pipeline.
 
 [gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables
-[logs]: /docs/concepts/signals/logs/
-[metrics]: /docs/concepts/signals/metrics/
 [telemetrygen]:
   https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen
-[traces]: /docs/concepts/signals/traces/