diff --git a/projects/2026/getting-started-redesign/_index.md b/projects/2026/getting-started-redesign/_index.md new file mode 100644 index 000000000000..7fa3777b4a76 --- /dev/null +++ b/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 diff --git a/projects/2026/getting-started-redesign/assets/step-1-role-selection.png b/projects/2026/getting-started-redesign/assets/step-1-role-selection.png new file mode 100644 index 000000000000..3239e163f920 Binary files /dev/null and b/projects/2026/getting-started-redesign/assets/step-1-role-selection.png differ diff --git a/projects/2026/getting-started-redesign/assets/step-2-language-selection.png b/projects/2026/getting-started-redesign/assets/step-2-language-selection.png new file mode 100644 index 000000000000..28d8baa6db6c Binary files /dev/null and b/projects/2026/getting-started-redesign/assets/step-2-language-selection.png differ diff --git a/projects/2026/getting-started-redesign/assets/step-3-signal-selection.png b/projects/2026/getting-started-redesign/assets/step-3-signal-selection.png new file mode 100644 index 000000000000..198d3a1bc163 Binary files /dev/null and b/projects/2026/getting-started-redesign/assets/step-3-signal-selection.png differ diff --git a/projects/2026/getting-started-redesign/assets/step-4-export-destination.png b/projects/2026/getting-started-redesign/assets/step-4-export-destination.png new file mode 100644 index 000000000000..9b954dca245e Binary files /dev/null and b/projects/2026/getting-started-redesign/assets/step-4-export-destination.png differ diff --git a/projects/2026/getting-started-redesign/assets/step-5-output.png b/projects/2026/getting-started-redesign/assets/step-5-output.png new file mode 100644 index 000000000000..1c924713a22e Binary files /dev/null and b/projects/2026/getting-started-redesign/assets/step-5-output.png differ