Rework .NET Docs - proposed mini-IA

[cartermp]

.NET is a little special. So I propose a mini-IA for the .NET docs:

Under instrumentation/.NET:

• Getting started
• Terminology and APIs
• OpenTelemetry API Shim
• Automatic
• Manual
• Exporters
• .NET Framework

Most .NET developers doing modern services work use modern .NET (i.e., not .NET Framework, which is a legacy Windows-based technology).

So, I propose that everything except for a page entitled ".NET Framework" (or something like it) uses modern .NET APIs - ASP.NET Core, Microsoft.Extensions.Hosting, etc. And in that one doc, the things you need to do to configure things for .NET Framework-based apps is covered instead, rather than putting it as an option for every single concept in the docs.

Additionally, since .NET recommends using the System.Diagnostics API over the OpenTelemetry API, there should be a dedicated doc that explains the difference and maps concepts from one to the other in a table.

Thoughts?

[chalin]

A few questions:

• Could Terminology and APIs (either or both the terminology or the API references) be a part of the index page?
• The main pages/topics for modern .NET are Getting started, Automatic, Manual and Exporters. Which of these topics would be covered under .NET Framework? Would it make sense to instead have a .NET Framework section at the bottom of each page?

[cartermp]

Could Terminology and APIs (either or both the terminology or the API references) be a part of the index page?

I think so, yes. At least certainly a terminology overview. The API reference itself is actually just here: https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics?view=net-6.0

...there's nothing in there about OTel (in fact, the core Activity class says it's for logging...), but, err, it's...there? Heh

Which of these topics would be covered under .NET Framework?

For .NET Framework, the main differences are in setup (where to "hook" in otel), and automatic instrumentation for ASP.NET (rather than ASP.NET Core, which doesn't run on .NET Framework). Everything else is the same OTel APIs, and exporters are even the same too (as far as I can tell).

So I think it could just be a separate doc.

[cartermp]

I think I will close this one out. After sleeping on it a few times, I don't think there needs to be a dedicated terminology&APIs section.