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

Missing overview of built-in components #18064

Closed rogihee closed 4 years ago

rogihee commented 4 years ago

It is hard to find information on built-in components like InputText and InputDate

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

guardrex commented 4 years ago

Hello @rogihee ... Those particular ones are in the Forms and Validation topic.

This is a good suggestion. I'll schedule this as P2 (Medium) priority issue. I'll get to it post-3.2 release.

Thanks for the suggestion!

guardrex commented 4 years ago

@mkArtakMSFT @scottaddie What do u think about the suggestion here?

The suggestion is for a TOC node has links the built-in Blazor components as a handy way to reach the content on them. The name is the component name, and the uid is the link to the topic that describes the component.

... or we need a topic called Built-in ASP.NET Core Blazor components that lists, briefly describes, and links their detailed implementation guidance.

... or we need a section of the existing Components topic with that content. However, note that there's concern on adding content to the Components topic. The topic gets too long easily when we continually add content to it. We even have an open issue to further split it.

scottaddie commented 4 years ago

@guardrex I agree that these native components should be easier to find. Looking at the ToC right now, I have no idea which doc to look at. As part of this effort, I recommend better organizing components topics. I suggest the following ToC structure:

guardrex commented 4 years ago

Yes, that looks great.

We're coming up to work on this and more general TOC issues. Perhaps, this and https://github.com/dotnet/AspNetCore.Docs/issues/18217 can be worked together. We'll need to chat more first. For example, would we go with WASM and Server sections in many topics, or an Overview of common content for each subject with one topic each under it for WASM and Server. Both approaches are currently in use. Anyway ... right now, we're obviously 🏃 on 3.2 work. I'll ping back perhaps late next week or the week after for further discussion.

mkArtakMSFT commented 4 years ago

I like @scottaddie 's suggestion. I'm now thinking whether Event Handling should also become part of that section or not.

guardrex commented 4 years ago

Here's the history. It's a reversal of the earlier decisions ...

  1. Back in blazor.net days, there was a components folder with today's topic in the overview slot (it just used it's current title instead of "Overview"). I felt we would need it one day, so I set it up that way, but we dropped it when the docs went into the official repo. IIRC, we dropped it because there wasn't a need ... just one topic with the understanding that it would be a long time before there would be enough topics to justify a node/folder.

  2. Later, it started to look like we might need a components folder again. I laid it out for consideration at https://github.com/dotnet/AspNetCore.Docs/issues/14353#issuecomment-532219598. @SteveSandersonMS said ...

    I think option 1 is fine [referring to going back to a components folder]. 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).

On the other issue (sections vs. topics) and https://github.com/dotnet/AspNetCore.Docs/issues/18217, which we'll discuss further over there soon, we're using both approaches in different spots:

  1. Some spots we have an Overview with separate Server and WASM topics under it. That makes sense when the content grows, grows, and 👹 GROWS! ... such as for Blazor's Security and Host and deploy content.
  2. Other topics have split Server and WASM coverage in sections of a single topic because the content hasn't grown like crazy, such as Hosting model configuration.

I've known about several UE problems in the TOC and topics for quite a while [e.g., TOC/content location, API doc links, common sample overhaul, messy topics (due to doc churn from new content)].

I've known about these problems for perhaps up to six months. 🙈 So why haven't I taken action? So many basic feature coverage issues have come my way due to product unit output and suggestions from the community that I haven't had time 🏃😅. The priority has been feature coverage.

By the time we get a plan in place for UE/TOC updates (and the other problems), I think two more weeks will have passed. I've had a great two weeks of catch-up thus far. I'm closing issues faster than they're being opened. I need another two weeks ... and hopefully some engineer vacations! 🏖️ ... and then these problems can be finally addressed.

mkArtakMSFT commented 4 years ago

It feels great to know that you're aware of the bigger problem and it's on your radar, @guardrex. I'll leave it up to you to handle when you get to it.