open-telemetry
Learn OpenTelemetry: New Getting Started & Best Practices
This is a follow up to https://github.com/open-telemetry/opentelemetry.io/discussions/4475 and a prototype for what I have described in this document.
To begin with, please ignore the implementation details and let's talk about the outcome, i.e. is this how we can move forward with providing a better "Getting Started" for OpenTelemetry.
Preview: https://deploy-preview-5376--opentelemetry.netlify.app/docs/learn/getting-started/
I see a few advantages in this approach:
- We remove the "Dev/Ops" Getting Started and replace it with a single (developer oriented) guide, that's focusing on natively instrumenting your application using the API&SDK, which is in line with our project's mission.
- We untangle a problem that we have been facing since we tried to have more consistent documentation across languages: we mix opinionated guides with technical references. Together with @jack-berg's work (see #4966 and #5276) we separate the 2 much more.
- We have a dedicated place that also allows us to have "Tutorials" (as suggested by @avillela), such that users can add some step by step guides to our documentation at a single place.
- With externalizing the example code to the language repositories + using code excerpts, we have a kind of "reference application" that showcases features per language consistently.
Very cool idea! Love the dropdown to toggle between different language options. Really hammers home the point that opentelemetry is a language agnostic toolkit.
This is a prototype, I will turn this in a draft PR, since we discuss this in https://github.com/open-telemetry/community/pull/2427/files
You triggered fix:all action run at https://github.com/open-telemetry/opentelemetry.io/actions/runs/12706084377
fix:all failed or was cancelled. For details, see https://github.com/open-telemetry/opentelemetry.io/actions/runs/12706084377.
Closing this since it was an experiment, will raise a new PR with suggestions for the information architecture changes
re-opening this to see if that will (temporarily) fix the link check failure in the community repo 😄
https://github.com/open-telemetry/community/blob/b8cb836fb1f4c01170c9bebff6985bac1f945e41/projects/new-getting-started-docs-and-reference-application.md?plain=1#L61-L63
