[docs][joy-ui] Change the customization and how-to guides docs tree #38396
Conversation
danilo-leal
added
docs
|
This way of organizing content is really helpful. It solves the problem with the 'how-to guides' category, which may not be clear to users since it can include different types of content like customization, integration, building blocks, or anything at all. By putting all this content under the 'Customization' category, it makes it easier for users to find what they're looking for. Even though the content on some pages can still be considered a 'how-to guide,' these guides are better organized when under the right section, making users feel more assertive since they know that everything under the 'Customization' section is related to customizing things. I would love to hear an opinion from a developer on this, though |
|
I have had this problem since the beginning about the separation between "Customization" and "How-to-guide". What I categorized in the how-to is the content as steps for achieving a specific requirement. I don't have any strong preferences and it would be nice if someone can come up with a rules/description of how we categorize the content. Happy to follow 😘 |
|
I think this is a big improvement! What you've hit on here reminds me of a chapter from Docs For Developers where they outline different types of content. They distinguish between Conceptual docs (for explaining key concepts and features of your product) vs. Procedural docs (for demonstrating how to accomplish a specific goal by following a set of structured steps). In this case, it appears that our Customization docs are mainly conceptual, while the Integration docs are procedural, so it makes a lot more sense to organize them this way. |
|
Also, I don't think "How-to guides" makes much sense as a section in the Material UI docs either, because the definition of what qualities as one seems to be very vague. I think that the entire information architecture needs to be overhauled over there, but that's a whole other can of worms. 😅 |
|
Sweet, yeah! Thanks for the book reference! I'm not sure if I had ever come across that one, will check it out! @samuelsycamore @siriwatknp @zanivan let me know if y'all think this is a good enough structure to roll out or if there's anything we need to sort out before doing it? |
There was a problem hiding this comment.
We are missing redirections, e.g. https://mui.com/joy-ui/guides/next-js-app-router/ is a 404 now. Fixed in a71e6a0.
|
ahrefs found more issues, fixed in #38761. We should always have each older URL in @siriwatknp Do you want to receive the ahrefs weekly craw? I should delegate ensuring the SEO health stays at 100% to each team. 
|
Sure! |
Another one from the series of "browsing around and looking for improvement opportunities" 😬
One thing that was getting me confused browsing around the Joy UI docs is that, previously, we had under "How-to-guides" two relevant customization-related docs which left me wondering... why aren't they under "Customization"? From a visitor's perspective, I'd need to bounce back and forth between these groups, which doesn't sound good. Like, to customize the theme's color, I go to the "Colors" page under the "Theme" sub-category. But to create themeable components, I go to the "How-to guides".
Through doing this change, I realized the ones left were much more integrations-oriented (i.e. how to use Joy with X), so thought about just calling that folder/section "Integrations"!
Generally, it makes me wonder about the "How-to guides" folder and what would be appropriate to be there and not under the "Customization" sub-categories... Looking at the Material UI docs as a benchmark, I think some pages there do make sense to be under "How-to guides" (e.g. Server rendering; Routing; Minimizing bundle size; etc.) but also think many of them could actually be under "Customization" (e.g. Localization; Right-to-left, Responsive UI; etc.).
I'm curious about what y'all think! Happy to ditch this PR if it doesn't make any sense but it is looking better to me, at least! 😃 Also took the liberty to simplify the URLs as well as the page titles a bit, thought there was an opportunity to be a bit more concise.
The number of files changed looks a bit scary but it's more because I moved files here and there from folders ⎯ but haven't altered anything inside them.
Examples: