Project proposal: Getting Started Redesign

projects/2026/getting-started-redesign/_index.md

@@ -0,0 +1,146 @@
+---
+title: Getting Started Redesign
+date: 2026-04-15
+lastmod: 2026-04-15
+version: 0.1
+custodian:
+  - Vitor Vasconcellos
+  - ...
+  - ...
+---
+
+## Description
+
+This project redesigns the Getting Started experience on opentelemetry.io by
+replacing the current content with a guided, step-by-step wizard. Inspired by
+[Certbot's instruction generator](https://certbot.eff.org/instructions), the
+wizard collects a few key choices from the user, such as their role, programming
+language, telemetry signals of interest, and export destination. Based on these
+inputs, the wizard generates a customized set of instructions that are tailored
+to the user's specific needs and preferences.
+
+The project resumes the efforts from the [New Getting Started Documentation and
+Reference Application][], which was previously started in
+[open-telemetry/community#2427][].
+
+## Current Challenges
+
+Before seeing any instrumentation code, users currently navigate from:
+
+1. [Getting Started][]
+2. Role selection: Dev / Ops
+3. Language documentation index
+4. Language getting-started page
+
+However, the language-specific getting started pages are often overwhelming for
+users, as they contain a lot of information that may not be relevant to their
+specific use case. Those pages are also heavily focused on **manual
+instrumentation**, which may not be the best fit for all users, especially those
+who are new to observability.
+
+## Goals, Objectives, and Requirements
+
+### The Wizard
+
+The wizard presents a short sequence of choices and generates a tailored
+getting-started guide. The following concept mockups illustrate the flow:
+
+> [!NOTE]
+>
+> These mockups are a starting point for discussion and are not intended to be
+> final designs. The actual implementation may differ based on feedback and
+> technical constraints.
+
+#### Step 1: Role Selection
+
+The user identifies as either a Developer or Platform Engineer / Ops.
+
+![Step 1: Role Selection](./assets/step-1-role-selection.png)
+
+#### Step 2: Language Selection
+
+The language grid only displays languages that have a completed reference
+application implementation. Languages without a reference app are not shown, as
+the reference app is a core part of the getting-started experience.
+
+![Step 2: Language Selection](./assets/step-2-language-selection.png)
+
+#### Step 3: Signal Selection
+
+The user picks which signals to start with: Traces, Metrics, Logs, or all three.
+
+> [!NOTE]
+>
+> Baggage and Profiles are intentionally left out of the initial wizard scope,
+> as they could be confusing for inexperienced users.
+
+![Step 3: Signal Selection](./assets/step-3-signal-selection.png)
+
+#### Step 4: Export Destination
+
+The user picks where to send telemetry: OTel Collector, Jaeger, Prometheus, or a
+Vendor / OTLP endpoint. The generated guide includes exporter configuration
+inline and links to setup documentation for the chosen destination.
+
+![Step 4: Export Destination](./assets/step-4-export-destination.png)
+
+#### Step 5: Output
+
+Based on the selections, the wizard produces a guide that includes install
+commands, environment variables, and instrumentation code for the rolldice
+reference application.
+
+![Output: Tailored Guide](./assets/step-5-output.png)
+
+### The Reference Application
+
+The rolldice reference application (defined by the [Reference Application
+Specification][]) remains the core example used in the wizard guides. Each
+supported language needs an implementation that follows the spec.
+
+### Alternative path: OpenTelemetry Demo
+
+For users who prefer to explore a full system before writing code, the
+[OpenTelemetry Demo][demo] remains available as an alternative path within the
+wizard — e.g., a "Try the demo instead" option on the first step.
+
+## Deliverables
+
+| Category           | Deliverable                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **Wizard UX**      | Interactive guided experience on the website that collects user choices and renders a tailored guide           |
+| **Reference apps** | Per-language implementations of the rolldice app following the existing spec, built through mentorship program |
+| **Guide content**  | Tailored getting-started content for each language / signal / destination combination                          |
+
+## Open Questions
+
+The following details are intentionally deferred for community discussion:
+
+- The Platform Engineer / Ops path needs its own set of wizard steps (deployment
+  target, Collector configuration, zero-code instrumentation options, etc). What
+  should that flow look like?
+- Does selecting a single signal filter the output content, reorder sections, or
+  just set expectations? The answer to this question may impact the amount of
+  content we need to create for each combination of options.
+- ...
+
+## Timeline
+
+This proposal intentionally does not include a detailed timeline, as the project
+is expected to secure conceptual buy-in on the overall approach before diving
+into implementation details. Once the high-level design is agreed upon, we can
+define a more concrete timeline with the milestones.
+
+## Related Resources
+
+- [New Getting Started Documentation and Reference Application][]
+- [Reference Application Specification][]
+
+[New Getting Started Documentation and Reference Application]:
+  https://github.com/open-telemetry/community/blob/main/projects/new-getting-started-docs-and-reference-application.md
+[open-telemetry/community#2427]:
+  https://github.com/open-telemetry/community/pull/2427
+[Getting Started]: /docs/getting-started/
+[Reference Application Specification]:
+  /docs/getting-started/reference-application-specification/
+[demo]: /docs/demo