Question on tutorial location for current and upcoming Blazor tutorials

[guardrex]

@Rick-Anderson and @wadepickett can probably answer my first question, and I ping @serpent5, for the second question with Rick and Wade. Per offline discussion, I mention @danroth27 and @mkArtakMSFT as well.

In the offline discussion that will lead to a public docs issue for Blazor Hybrid work, the plan is to have three Blazor Hybrid tutorials. In that discussion, pain points came up WRT where tutorials live in the doc set today. I believe that the current tutorial location at aspnetcore/tutorials/... is a fixture of ancient doc times 👵👴.

Two questions on this ...

1. What was the reason for grouping all of the tutorials in the repo this way and not with their individual technology coverage?

   I'll demo this with Blazor. Today, we have the following layout ...

   • aspnetcore/blazor/doc-1.md
   • aspnetcore/blazor/doc-2.md
   • aspnetcore/blazor/doc-X.md
   • aspnetcore/tutorials/blazor-doc-1.md
   • aspnetcore/tutorials/blazor-doc-2.md
   • aspnetcore/tutorials/blazor-doc-X.md

   ... versus the layout that could've started back in beta Read the Docs times 👵👴 ...

   • aspnetcore/blazor/doc-1.md
   • aspnetcore/blazor/doc-2.md
   • aspnetcore/blazor/doc-X.md
   • aspnetcore/blazor/tutorials/doc-1.md
   • aspnetcore/blazor/tutorials/doc-2.md
   • aspnetcore/blazor/tutorials/doc-X.md

   ... i.e., similar to what we do with sample apps and snippet code for topics.

   From an SEO perspective, I gravely doubt there is a difference between these layouts given that I always use the word "blazor" in the topic file name (e.g., /aspnet/core/tutorials/build-a-blazor-app). With the latter layout, the word "blazor" would always be present in the path (e.g., /aspnet/core/blazor/tutorials/build-a-todo-list-app ... or something along those lines). I wouldn't strictly need the word "blazor" in the tutorial's file name, as I do today.

   From a doc maintenance perspective, I don't understand the utility of the current design: Who of us only works in the tutorials folder with the full array of those docs and nothing else? Does anyone ever only use a single VSC filter string in search for the tutorials folder? I don't. I don't think I've ever done that even once in ... what? ... five years now.

   From a reader perspective, it feels like the Tutorials node in the sidebar ToC is painful to use. Surfing the site, I'd prefer a topic (.md) in the root, and not need to flip open all of those little ToC sub-nodes. Also ... I think you're aware of this ... the sidebar ToC chokes navigation on multiple entries in the toc.yml file for the same topic when the reader is trying to stay on one technology. It seems to match the highlight cue to the first entry that matches their URL regardless of which node they were just reading in, which is why you see that I host a Tutorials topic (.md) in the Blazor node these days. Still tho, navigation breaks if they go to a tutorial without a link at the bottom getting them back to the Blazor Tutorial topic.

   Anyway, I realize that the 🎲 has been cast on this to a great extent repo-wide. It would take an army of 🐘🐘🐘 to move that mountain for the whole repo. I really would be surprised if a major direction change was taken. I'm merely asking why this layout was chosen in the first place? For example, is there (or was there) a doc division rule on this that was merely being followed in spite of some rough edges?

2. Do you mind if we place Blazor tutorials in the blazor folder (i.e., aspnetcore/blazor/tutorials/...)? It would speed me up 🏃.

   • With the tutorials in the Blazor folder, I would only need ...

     ./aspnetcore/blazor/**/*.md

     ... or without the ".md" to capture everything.

     🎤 drop ... Done. 😄

   • Today, we start with ...

     ./aspnetcore/blazor/**/*.md,./aspnetcore/tutorials/signalr-blazor.md,./aspnetcore/tutorials/build-a-blazor-app.md

     ... and it's even a little worse when I need to add the Blazor-SignalR tutorial sample apps filter string to that.

     ... BUT, we'd be adding three more tutorial topics to that. It's going to get a bit nutty 😵. I often forget or don't notice that I'm missing the tutorial filters ... then I end up missing API/text/example code. When I do, I then need to create a whole new PR to fix what I missed 🙈 ei ei ei.

   If the answer is ultimately, "NO! We're about to send u to the dino graveyard, Rex!" 💀⚰️😆 It's cool. I can keep going with the current paradigm of aspnetcore/tutorials/.... This is a good time to ask tho, before the proverbial stuff hits the fan on new Hybrid tutorials landing. It will break consistency a hair, but I recommend adopting my proposal just for the Blazor tutorials.

[Rick-Anderson]

Do you mind if we place Blazor tutorials in the blazor folder (i.e., aspnetcore/blazor/tutorials/...)? It would speed me up 🏃.

Fine by me. In the original design we didn't have Razor Pages and Blazor. It's suboptimal for sure.

[wadepickett]

Yes, all the Blazor content would be best kept together, including its tutorials. The TOC and landing pages can group content from across separate technology areas where needed.