Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Learn OpenTelemetry: New Getting Started & Best Practices #5376

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

svrnm
Copy link
Member

@svrnm svrnm commented Oct 10, 2024

This is a follow up to #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 Refactor java SDK and configuration #4966 and Refactor java instrumentation #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.

Signed-off-by: svrnm <neumanns@cisco.com>
Signed-off-by: svrnm <neumanns@cisco.com>
Signed-off-by: svrnm <neumanns@cisco.com>
@svrnm svrnm requested a review from a team as a code owner October 10, 2024 14:34
@jack-berg
Copy link
Member

Very cool idea! Love the dropdown to toggle between different language options. Really hammers home the point that opentelemetry is a language agnostic toolkit.

Screenshot 2024-10-10 at 10 06 14 AM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: No status
Development

Successfully merging this pull request may close these issues.

2 participants