Aspnetcore.docs: Consolidate troubleshooting docs between azure-apps and iis

[jkotalik]

Right now, the troubleshooting docs between azure apps and iis have a lot of duplication between them. We should consider cross-referencing shared components to minimize duplication.

There are also many issues filed in ASP.NET Core that effectively say "500.30 ANCM Startup failure". I think it would be nice to have an equivalent doc that SignalR has for diagnostics: https://docs.microsoft.com/en-us/aspnet/core/signalr/diagnostics?view=aspnetcore-3.0. This can also use cross-referencing to share details with troubleshooting.

cc @guardrex @shirhatti @anurse thoughts?

[anurse]

I think this is a great idea. That SignalR doc has been a fantastic resource for improving the quality of user bug reports. Even if they don't find it immediately, we can respond to bug reports with "Check out this doc and use it to collect some logs pls?" and they either find the issue and realize it's their code, or give us much more detailed information that makes reproduction and investigation easier.

[guardrex]

This might be tricky to pull off. The instructions for working in the two scenarios aren't the same in several respects.

Azure ...

• Relies on Kudu for some approaches.
• Has different paths that it must call out.
• Uses monitoring blades for some scenarios.
• Has cross-references to specific content in Azure docs that only apply to Azure scenarios.

It might work out ok ... it's just a point of concern that I have. I see the duplication. However if the process of dealing with those duplicated aspects (the same error or logging) results in just cutting-and-pasting full sections from each doc into one, I wonder if it really accomplishes anything. If I were an Azure reader or an IIS reader, I'd only want to see what applies to my scenario and not have to skip/read past a lot of non-applicable guidance.

Seems like a draft of the combined doc would help understand how this might work. Do you want me to give it a go and see how it turns out? If so, I need more detail on "cross-referencing" ... what exactly do u want to do? Combine topic content into one doc that resides in the Test, debug, troubleshoot area of the TOC, then cross-link that from the Host and deploy node topics (and elsewhere)?

[jkotalik]

Regarding Azure:

Relies on Kudu for some approaches.

I reallllly wish we didn't need to rely on Kudu. But I agree that is a difference.

just cutting-and-pasting full sections from each doc into one, I wonder if it really accomplishes anything.

For example, this PR I just made has two entirely duplicated sections https://github.com/aspnet/AspNetCore.Docs/pull/12605

Do you want me to give it a go and see how it turns out? If so, I need more detail on "cross-referencing" ... what exactly do u want to do? Combine topic content into one doc that resides in the Test, debug, troubleshoot area of the TOC, then cross-link that from the Host and deploy node topics (and elsewhere)?

Let's start with just cross referencing between IIS and azure apps with a shared source. I'll take care of the creating a doc for diagnostics/test/debug/troubleshoot. after we flesh out some of the structure.

[guardrex]

I'm still working toward #12605 ...... buried in a Blazor tutorial at the moment but hope to be free soon.

[Rick-Anderson]

I reallllly wish we didn't need to rely on Kudu. But I agree that is a difference.

Kudu is often the best tool to debug on Azure.

@guardrex how clumsy would it be to put the shared content in includes? If it's alot of includes and only used in two places, you're usually better off copy/paste with internal <!-- Comment, this is copied from -->.

[guardrex]

Significantly shared content ... almost duplicated exactly ... is the bit at the tops of these docs that describe the way errors manifest themselves (mostly HTTP status+messages in the browser IIRC).

I'll take a 🔪 stab at getting one topic in the Test, debug, troubleshoot area. If these two topics combine well into one topic, then there won't be a need for INCLUDES. Hopefully, they will compose well into one topic. 🤞

[guardrex]

NOTE: This issue remains open because more work is planned. On #12954, the process was started ... combination and relocation of troubleshooting topics. More content work is on the way tho in a future PR. The details are TBD at this time (6/28). I'll move this out to the July sprint for now.