[material-ui][docs] Categorize the "How-to guides" pages

[danilo-leal]

• I have followed (at least) the PR section of the contributing guide.

This PR attempts to add some categorization to the Material UI "how-to guides" pages. I've felt they needed something like this for a while, as there are already multiple pages with different purposes.

https://deploy-preview-40403--material-ui.netlify.app/material-ui/guides/material-3-components/

[mui-bot]

Netlify deploy preview

• docs/data/material/components/bottom-navigation/bottom-navigation.md
• docs/data/material/components/buttons/buttons.md
• docs/data/material/components/links/links.md
• docs/data/material/components/lists/lists.md
• docs/data/material/components/tabs/tabs.md

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 0bfc2b0

[oliviertassinari]

It reminds me a bit of this docs reorganization discussion: #39972 (comment).

[DiegoAndai]

What do you think about:

• Moving the customization ones to the customization section
• Moving the integrations to a new integrations section
• Moving "Migration from @material-ui/pickers" into the migration section
• Having the crucial guides without a subsection and a "General" section for more overview stuff:

[danilo-leal]

Yeah, I was hesitant to move things around too much on this PR for the sake of not having SEO impact, but your suggestion makes sense, and as I also mentioned in the description, there are generally more sorting improvement opportunities! Here's an iteration I'm playing with after your comment, and it's making sense to me, but there would be an impact on SEO as the path changes for some of these pages. Let me know what y'all think about this:

Customization	How-to guides	Migration	Integrations

(There's also an opportunity to improve the theme-related pages there — the "Theming", "Creating themed components", and "Components" pages are all confusing as in they seem to be talking about very similar things, mainly the last two. Similarly with "Palette" and "Color").

[DiegoAndai]

I was hesitant to move things around too much on this PR for the sake of not having SEO impact

I cannot contribute to the SEO discussion as I have minimal experience.

The proposal makes sense from an information organization structure, though 👍🏼.

I propose a more significant change as I would like to fix this issue once and for all rather than return to it in 6 months.

[samuelsycamore]

I'm glad to see this PR! I was just about to open an issue to discuss this after reviewing the Material 3 guide and seeing how long this list has gotten. I also can't speak to the SEO impacts (other than the annoyance of all the redirects we'd have to add), but I would also prefer to see these subsections bumped up another level higher. There's so much space to work with in this sidebar, and it doesn't seem necessary to group all of these docs together when they cover so many different kinds of topics.

In terms of implementation, I agree that it's weird to have two sections called Customization, and I don't see why those "how-to guides" couldn't be moved into the original Customization section. Instead of "General," what about something like "(Key) Concepts," since most of the these guides talk about the mental model of working with Material UI. (Some of the other "how-to guides" like routing, server rendering, etc. could also fit here.) And I think Integrations definitely deserves its own section.

[danilo-leal]

@oliviertassinari — any thoughts here? Maybe a more SEO-oriented perspective?

[danilo-leal]

@oliviertassinari — additional bump here! Let me know your thoughts on the proposal at #40403 (comment) and potential SEO consequences!

[oliviertassinari]

@danilo-leal On the SEO front, I'm not aware of any correlation between the link orders in the page and SEO. The changes look independent.

Redirections are not great for SEO, but I think it only matters for pages new users discover MUI from. The pages we are talking about don't seem SEO important.

Otherwise, the grouping makes sense. It stays simple but with a bit more order (not too much).

Let me know your thoughts on the proposal at #40403 (comment)

Where would the Framework content would go in the future (guide content type) #39972 (comment)?

[danilo-leal]

Okay, great — thanks for the feedback! I just committed the proposal I posted on #40403 (comment), and they might mean some URL changes, which I assume affect SEO to some extent, but as you said, these aren't necessarily "SEO-heavy" pages, and there wouldn't be a lot of changes, too!

Where would the Framework content would go in the future (guide content type)

I would intuitively think they belong in the Integrations section—that is, if we want to have specific pages for each "framework" (if that applies to us), as we've recently done with Next.js.

[danilo-leal]

Latest changes on the commit above include:

• Removed the "General" subsection on the How-to guides. I felt like I was mostly adding it due to the "Understanding MUI packages" link, which I ended up moving to the Getting started section as it feels like something worth knowing to start off with proper context.
• Also removed the "General" subsection on the Customization section, and just moved the pages that felt broader to the top.

[samuelsycamore]

• Removed the "General" subsection on the How-to guides. I felt like I was mostly adding it due to the "Understanding MUI packages" link, which I ended up moving to the Getting started section as it feels like something worth knowing to start off with proper context.

FYI the Understanding MUI Packages page has been removed in the latest release as part of #39724

[danilo-leal]

Bumping this one up — any thoughts/concerns? Would love to get a review :)

[oliviertassinari]

I imagine we left the links broken before the structure is agreed on to avoid double work, to fix before merging though.

[alexfauquette]

I've made vale as not failing is case of error

@oliviertassinari I know you're in favor of having a PR failing to force devs to fix it and avoid accumulating mistakes. But here it was failing just because for more that 50 warning the action adding message fails. So it's the only solution I can think about (except solving all the warning in the files @danilo-leal moved

[danilo-leal]

Woo, thank you @alexfauquette! I definitely think we should resolve all of the Vale errors that were being picked up here, but that also means revising the copywriting for several pages, which is a big endeavor, to unblock this PR. It doesn't feel like these things need to be that tied together :) @oliviertassinari would love a double-check here from you.

[danilo-leal]

Little bump on this one!