Topic needs to be restructured to be easier to understand and use

[Maintenance-Partnership-Systems]

Description

I find this topic, as written, to be too difficult to follow and to determine what actions I need to take for my particular project. I feel that it would be better if it were instead broken down in the first instance by scenario, with each different deployment scenario clearly isolated into its own section - preferably on a separate page for each scenario or variant scenario so things are clearly separated. Each scenario could then be dealt with as a clear and simple set of 'necessary steps', with diversions into background details linked separately, so as to keep the set of 'necessary steps' as clear and simple as possible.

Further, it needs to be written assuming only minimal knowledge of the whole environment. The challenges of deploying an app to a server can come up very early on in a developers experience with the environment, and often in circumstances where they are time-poor and under pressure to get the deployment done. The article should be written with that in mind.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/?view=aspnetcore-9.0&tabs=visual-studio

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/blazor/host-and-deploy/index.md

Document ID

c82cf121-831d-75dd-a796-c735aad3b3e9

Platform Id

503f69d7-fc1b-3879-cc1d-b6775ebf03cc

Article author

@guardrex

Metadata

• ID: e07aaa4d-4ad4-778f-f74a-60d8f05d9075
• PlatformId: 503f69d7-fc1b-3879-cc1d-b6775ebf03cc
• Service: aspnet-core
• Sub-service: blazor

Related Issues

[github-actions]

🌱🐇 Spring is coming. Hang in there! I'm pull'in for ya! 🐣🌻

Stand-by! ... A green dinosaur 🦖 will be along shortly to assist.

[guardrex]

Hello @Maintenance-Partnership-Systems ... Thanks for the feedback. I already plan to reorganize the content in this node, which is tracked by #34434. What I plan to do is introduce two folders in this node, one for server-side scenarios (Blazor Server/Blazor Web Apps) and one for client-side (Blazor WebAssembly). I further intend to split out some of the sections in these articles into different articles that will be placed in those nodes.

WRT this overview, there are only server-side Blazor apps (Blazor Server, Blazor Web Apps) and Blazor WebAssembly apps; and beyond the publishing step, which explains where the deployment assets are located, the two articles that focus on these types of apps are cross-linked and in this node. There's nothing else for the overview to cover besides the app base path, cross-links to IIS resources, and cross-links to the two articles that cover each type of Blazor app. I might split out the app base path coverage into its own article under the overview.

each different deployment scenario clearly isolated into its own section - preferably on a separate page for each scenario or variant scenario so things are clearly separated

They are. The server-side coverage is in one article, and Blazor WebAssembly is covered in a different article. Each section of these articles is almost clearly defined. IMO, we have a problem with our doc styles that don't distinguish sections well because the font size doesn't change enough across H2s/H3s. Unfortunately, we don't control that. It's a Microsoft-wide docs style. There is an opportunity to simplify the whole presentation by splitting out H2 sections, especially long sections, into separate articles.

Each scenario could then be dealt with as a clear and simple set of 'necessary steps', with diversions into background details linked separately, so as to keep the set of 'necessary steps' as clear and simple as possible.

needs to be written assuming only minimal knowledge of the whole environment

"Necessary steps" can mean virtually anything because it's very host and environment specific. We're limited on what we can do in a framework doc set to address individual hosts, and devs should consult host-specific guidance for more information. However, we do have basic configuration information. That's probably as far as we can go with this subject.

Management hasn't asked for tutorials for each major host (IIS, Nginx, Apache), but I did write out GH Pages for Blazor WebAssembly because it's tricky to get right. I think that section should definitely be split out into its own tutorial. It's worth considering for the future that we'd maintain a tutorial each for BWAs and Blazor WebAssembly apps for each popular host, but it's very time consuming to produce that much content and possibly challenging to maintain given our limited resources (time! 😄).

Also, the server-side scenarios are an add-on doc set to the main doc set's Host and deploy resources because server-side Blazor apps are ordinary ASP.NET Core apps. For example, there is an IIS deployment tutorial, which is cross-linked in the overview's IIS section and Server article's IIS section, that should work fine for server-side Blazor apps. The Blazor WebAssembly article covers each deployment scenario with differences to ordinary ASP.NET Core apps; although, splitting them out into individual articles is a good idea.

For specific host guidance, devs must seek out docs for specific hosts, Microsoft articles for Microsoft technology/services, especially the IIS, Kestrel, and Azure coverage, and external doc sets for non-Microsoft hosts. I'd like to do a better job cross-linking the existing resources.

I'll try to work on this soon, hopefully within the next few weeks. It's a big job that must be dovetailed with the important work on .NET 10 coverage for November, but there's usually enough time during the early previews to work on large jobs like this.

Thanks for the feedback, and you'll see some nice improvements after I work on the node.