Migrate `/docs` content that is end-user facing to OpenTelemetry Website

[svrnm]

Hi @open-telemetry/dotnet-maintainers & @open-telemetry/dotnet-approvers,

while working on an update for the .NET documentation over at https://opentelemetry.io/docs/languages/net/ I ran into the very valuable resources you host in your /docs folder.

It would be great if the documentation in that folder that is end-user facing (most content that is not in "customizing the sdk" folders) would become part of the docs on the opentelemetry.io website.

Happy to facilitate the migration.

Thanks, Severin from Docs (cc @open-telemetry/docs-approvers)

[theletterf]

Happy to help as well, I've been editing those docs recently.

[cijothomas]

https://github.com/open-telemetry/opentelemetry-dotnet/issues/2333 Prior issues.

Yes, we need to make sure the docs have a single source of truth. The current state of 2 separate source for docs is not good.

[chalin]

Prior issue:

• 2876

Context:

• https://github.com/open-telemetry/opentelemetry.io/issues/833

[svrnm]

Thanks for sharing the existing issues. We can follow up there, but I just wanted to check in with the .NET SIG on how to proceed with that.

[svrnm]

@open-telemetry/dotnet-maintainers @open-telemetry/dotnet-approvers please take a look at this!

[svrnm]

@open-telemetry/dotnet-maintainers @open-telemetry/dotnet-approvers please take a look at this!

[cijothomas]

It would be great if the documentation in that folder that is end-user facing (most content that is not in "customizing the sdk" folders)

customizing the sdk folder is equally end-user facing!

[cijothomas]

@open-telemetry/dotnet-maintainers @open-telemetry/dotnet-approvers please take a look at this!

We are short on manpower at the moment (2 maintainers stepped down in the last 1 year, and 1 other maintainer is less active as well), so didn't have time to look at how to carefully execute this and ensure any concerns are addressed.

The overall structure in docs website is different, so this effort will not be just a lift-and-shift, and requires refactoring etc.

Additionally, some of the nicer APIs to make it super easy to configure OTLP won't be released until later this year, so it maybe okay to wait until that time, so as to avoid lot of churn in the docs...

[svrnm]

@open-telemetry/dotnet-maintainers @open-telemetry/dotnet-approvers please take a look at this!

We are short on manpower at the moment (2 maintainers stepped down in the last 1 year, and 1 other maintainer is less active as well), so didn't have time to look at how to carefully execute this and ensure any concerns are addressed.

Thanks, @cijothomas! I understand the concern with man power, but we (@open-telemetry/docs-approvers) can help with that based on the needs of specific SIGs. We did some of the heavy lifting for other SIGs as well, so we potentially can do the same thing for .NET. The important thing for me is that we engage in a conversation around it!

The overall structure in docs website is different, so this effort will not be just a lift-and-shift, and requires refactoring etc.

We can discuss how much we can just adopt the structure in the /docs folder as a starting point and how much can be de-duplicated based on the fact that content is basically the same.

I see that there is activity in the /docs folder, so from my perspective, I would prefer that time and energy being spend on opentelemetry.io/docs instead. And again, it's our responsibility to help you with that.

Additionally, some of the nicer APIs to make it super easy to configure OTLP won't be released until later this year, so it maybe okay to wait until that time, so as to avoid lot of churn in the docs...

Thanks for the heads up! We can drive this at the appropriate speed for .NET SIG.

[cijothomas]

@svrnm TBH, I don't know how much is the actual effort. From a very quick look - it is a lot! Just to give a simple example - In this repo, it was decided to show separate getting started guides for hosted (asp.net core) apps and non-hosted apps (console). The docs website getting started is showing the asp.net core one, in alignment with rest of languages as they all show a web app. Some refactoring is needed here.

This repo shows separate getting started guide for logs, metrics and traces, along with a set of best-practices/faqs and associated .csproj files. Docs website currently has all signals bundled together, and offers a separate API ref for traces and metrics, which simply points to .NET official docs page. Need to find a common ground for this.

Not an unsolvable problem at all, just need some dedicated time to make it happen.

I see that there is activity in the /docs folder, so from my perspective, I would prefer that time and energy being spend on opentelemetry.io/docs instead

Its mostly status quo. We already have docs there, so anything new is added there as well. We can't stop updating that unless we completely move off to docs website.

This is worth discussing in OTel .NET community call, to see what are the main challenges, and how best to orchestrate the whole thing.

[mtwo]

Following up from the SIG call: there's broad agreement to move most of the documentation to the opentelemetry.io website, similar to what other SIGs have done. As @cijothomas points out, this will require some work and prioritization. I think that we'll use #5779 as our first pass at this, and it'll also be our first attempt to create more comprehensive getting started guides on the website. As @svrnm mentioned, the docs team will assist with this effort.

[svrnm]

Thank you all! I am looking forward to make some progress here.

I think as a first starting point, we should look at the things we have already, and then it would be important for me to understand what is important for the .NET SIG to have in the documentation and what they miss in the current content available at https://opentelemetry.io/docs/languages/net/.

On Aspire: I do not think that it is a good starting point for the migration. Before we add it to the website (or any other documentation), we need to have a broader discussion what visualizations we promote on our website. If we do Aspire on one page, why not Elastic, Embrace, Grafana, Highlight, HyperDX, OneUptime, OpenObserve, SigNoz or any of the other open source ones on another (or the same page)? That's why we until now restricted ourselves to CNCF projects (jaeger, prometheus) even if none of them supports all signals to show no visualizations in the documentation (blog posts are different). We can change that, but then we have to accept the implications. I will raise a discussion for that on the opentelemetry.io repo, since this is the way how we drive these kinds of decisions. Let's move this discussion out in a dedicated place at: https://github.com/open-telemetry/opentelemetry.io/discussions/5040, such that we can focus on the migration discussion in this issue.

Note, that I will have limited to no availability starting tomorrow until Sept, 3rd.