Restructure sections to separate UWP and .NET Standard

[Sergio0694]

The toolkit currently includes a number of APIs that are not UWP-specific, with more targeting .NET Standard on their way as well. Right now it's difficult to see at a glance which APIs are only available on UWP and which can be used from any kind of .NET project instead.

It'd be nice to restructure the sections (eg. with two main "UWP" and ".NET Standard" sections) to clearly separate the two main types of APIs. This would also make life easier for devs working on .NET Standard projects (or .NET Core, or any other portable runtime), as they'd be able to just expand the ".NET Standard" section and look at APIs available there, instead of having to double check the framework/namespace of each API across the various sections.

cc. @michael-hawker

[michael-hawker]

Should also better separate the UWP based controls from the XAML Islands helpers.

[michael-hawker]

We should also make sure all our blocks at the bottom are updated to differentiate between .NET Standard vs. UWP as was called out here: #302 (comment)

[Sergio0694]

I was in the process of writing the docs for CommunityToolkit/WindowsCommunityToolkit#3353 and I think I've identified another big improvements we could add to the docs for the toolkit, assuming this is possible.

Right now, writing the docs for a new control/helper requires contributors to perform the following steps:

✅ Create the page, add it to the toc.file
✅ Write the introduction for the new thing
✅ Write a section to detail how it works
✅ Possibly write a section to show the usage/syntax
⛔ Manually copy all the properties and their docs/info
⛔ Manually copy all the methods and their docs/info

I would argue the current workflow is not ideal, especially for new developers. The steps with the green checkmark are perfectly fine and those should be the only ones required for contributors. There are a number of issues with the last two steps:

• They're pretty error prone, as you need to just copy every single API that's exposed
• They lack contextual info on their arguments/returns, as right now they're all just plain text.
• They lack info on all arguments, as we're just indicating the types for brevity.
• If a devs want to know more on one of them (eg. read the rest of the XML docs), they need to manually search for that API in the docs. They're not linked - they're literally all just plain text.
• They immediately get out of sync if there's any change in one of the APIs and the contributor forgets to also update the docs.
• They're extremely boring to write 😅
• Literally all this info is perfectly duplicated (and done better) in the autogenerated docs anyway.

Consider this example from the docs for the SpanOwner<T> type:

Compare that with the autogenerate section from the same type (here):

Much better! 😄

For the reasons listed above, I don't think just asking contributors to spend more time eg. adding hyperlinks etc. to their hand-crafted docs is a good solution, ideally we'd just want to rethink this strategy here entirely. A few possible options:

• Just have the hand-crafted docs be for usage/overview/explanation, and just link the others for the actual APIs list
• Have the MS docs website autogenerate that same table with properties/methods for the hand-crafted docs (eg. we could have a custom widget like that > [!NOTE] one that can be used to tell the MS docs website to just load the APIs table for a given type at a specific spot in a markdown file. Like:

> [!API-PROPERTIES](microsoft.toolkit.highperformance.buffers.spanowner-1)

> [!API-METHODS](microsoft.toolkit.highperformance.buffers.spanowner-1)

This second one was just an idea and I realize it'd be more complex to do as it'd require some work from the MS docs team too. Personally I'd be fine with the first one as well at least for now, as I'm not really convinced the current docs creation procedure is ideal, for the reasons listed above.

Just some thoughts I had while writing the docs, hope this helps! 😊
I thought I'd share since we mentioned we wanted to restructure the docs anyway for the future.

cc. @michael-hawker @azchohfi

[michael-hawker]

We can also physically move files around, but we need to create a redirect file. I need to grab an example from another docs repo, but this would be handy, especially for archived content.

For now we just have to leave things as is and update the TOC for 7.0, and we'll fix this with a docs revamp for 7.1.