search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.64k stars 25.29k forks source link

Improve Blazor component lifecycle page #14353

Closed SteveSandersonMS closed 4 years ago

SteveSandersonMS commented 5 years ago

[EDIT by guardrex to add DR's notes from the 1st PR to this opening content list]

[EDIT by guardrex to update on work done and check off work items that have been completed since this issue was opened]

[EDIT by guardrex to remove plan to create a new lifecycle topic ... that's done]

This is a suggestion that it's time to address a whole bunch of "how to do..." question issues that we've been collecting in response to developers' questions:

Expand content to include:

From DR on the PR to create the initial Lifecycle topic

Instead of focusing purely on the lifecycle events I think we want this article to explain more broadly how components work, like how and when the render. We should walk the user through a day in the life a component in a Blazor app. The lifecycle events are then just specific points that you can plugin your specific behaviors.

Things that I think should be covered:

WRT the short State changes (StateHasChanged) section ...

I think this section would fit in better with a broader description of how and when components get rendered. Right now this section on StateHasChanged feels a bit out of context.

SteveSandersonMS commented 5 years ago

cc @mkArtakMSFT @danroth27 @rynowak since we already did the first cut of docs triage yesterday.

guardrex commented 5 years ago

we're going to have to split up the giant "components" doc page into smaller pieces

We had a Components node to hold multiple topics because I thought that things would go in this direction. I wasn't allowed to keep that node (https://github.com/aspnet/AspNetCore.Docs/pull/10716#issuecomment-459464236), so it was dropped.

Options ...

  1. Would you like to go back to a Components node (folder)? The current Components topic becomes the Overview/index of the node, and we can easily split out content and create new topics as needed.
  2. Do you want to stick with what we have? Do you want to split this topic up into several topics that live out in the open Blazor node?
  3. Have you devised a different TOC for basic and advanced components topics that we can put into place now?
SteveSandersonMS commented 5 years ago

By all means let's solve the question of how to manage the rest of the "components" material, but I think it can be independent of this specific work item.

My proposal here is just a first step: to split out the lifecycle topics described here into a separate docs page as a sibling of "components", "component libraries", "routing", "js interop" and so on. There's nothing inconsistent about that, since literally all these pages are about doing stuff with components.

guardrex commented 5 years ago

it can be independent of this specific work item

We're only explicitly allowed to change the physical TOC (i.e., physical folders/URLs) and UIDs now ... in preview. After 3.0 GA, it will take an :pray: act of the server gods :pray: to change the physical TOC/UIDs. I strongly recommend doing it now ... like today. :smile: lol

My proposal here is just a first step: to split out the lifecycle topics described here into a separate docs page as a sibling of "components", "component libraries", "routing", "js interop" and so on. There's nothing inconsistent about that, since literally all these pages are about doing stuff with components.

Some of your phrasing and words are overloaded, so I don't follow. Explain it out in terms of TOC nodes (folders). I'll lay out the options below ... which direction would you like to go?

[EDIT] ... and keep in mind this pertains to physical folders, which produce the topic URLs. The sidebar TOC of rendered docs is never a problem to change ... we change that all the time. Let's get the folders/URLs right.

Option 1: All components subject matter topics are at the same level in the Blazor node (folder).

Option 2: Go back to a Components node (folder) and put the components subject matter topics in that node (folder) ... BUT ... leave the other 'stuff you do with components' topics where they currently are in the Blazor node (folder).

Option 3: Go back to a Components node (folder) and put the components subject matter topics in that node (folder) ... AND ... move the other 'stuff you do with components' topics into that Components node (folder), too.

Option 4: Something else

Whatever u decide to do WRT nodes/physical folders for URLs and UIDs ... please let's do it now ... in preview ... this week! :smile: lol

SteveSandersonMS commented 5 years ago

I think option 1 is fine. I don't think there's any real advantage to arguing for an extra level of nesting. Customers won't see any difference as long as they can find the content they want, plus I don't think these topics are truly nestable in any objective way (e.g, there's lots of components-related stuff in the other non-"components" pages already).

guardrex commented 5 years ago

Indeed, yes, no changes is the happy path. :smile: I'm just saying that if such changes are desired, let's make them now.

guardrex commented 4 years ago

Several of the issues here have been resolved, and we should split the remaining pieces into different work items: