[core][docs] How should "overlapping" components and features be documented?

[samuelsycamore]

Problem

The 4 Core products—Material UI, Base UI, Joy UI, and MUI System—contain a fair amount of overlapping components and features, and it's not always clear when we should duplicate content within individual product spaces, vs when we should redirect users to a single source of truth on a topic. Users consistently express confusion about pages where we attempt to redirect them; on the other hand, it can be cumbersome for us as maintainers to keep track of pages where content is duplicated when it needs to be updated.

Callouts like this:

...lead to feedback like this:

...but the alternative is that we maintain essentially identical pages in the Material UI, Joy UI, and MUI System docs. But why should we do that, if the Box is technically an MUI System component that's shared across the other two libs?

There are trade-offs to both approaches:

Trade-offs

Redirecting content / single source of truth

Pros

• much simpler for us as maintainers - single source of truth to keep track of
• opens the door to teach users more about the MUI ecosystem and related / complementary products

Cons

• can be frustrating / confusing: "why do I need to read some other product's docs?" "where is the information I need?" "I don't know what this MUI System thing is, I'm just trying to use Material UI" etc
• bad for SEO - a page with no useful content that just redirects somewhere else will get de-ranked by search engines
• requires knowledge of the MUI ecosystem that a newer or more casual user shouldn't be expected to have
• leads to a worse Algolia search experience (IMO) - I follow the link to the Material UI Box page, but when I get there it has no useful info for me. So then I'm wondering, why is it even here at all?

Duplicating content across product spaces

Pros

• users never have to leave the documentation for the product they're actually working with: less jumping around == better experience
• better delineation of products - I don't need to know anything about MUI System or how it relates to Joy UI or Material UI to use the Box component
• better for SEO - high quality info on each page
• better Algolia search - even if you land in the wrong product space, you'll (probably) still find the info you need to get unstuck

Cons

• cumbersome for us as maintainers - could have 4 pages that say essentially the same thing and all need a link updated or a typo fixed, but any given contributor can't be expected to know every place where content is repeated

Duplication wins (?)

When I weigh the pros and cons, it seems clear to me that duplicating content is preferable over redirecting. The only major downside is that it's kind of annoying for maintainers, but the benefits to the user experience are worth the inconvenience IMO.

Others are welcome to add other considerations to my list—I could be missing some key points that could tip the scales in the other direction, and I'm open to having my mind changed about this. 😁

Exceptions

That said, I think there are some pages where redirecting makes sense: specifically, the pages in the Material UI docs that redirect to Base UI, and warn the user that these utility components (Click-Away Listener, No SSR, etc) will be removed from the next major.

In this case, the redirect is (ideally) temporary, and the page simply won't exist in the Material UI v6 docs because those components won't be part of the package anymore.

What do you think?

I'd love to hear what others think about the trade-offs here, for users, contributors, and maintainers alike.

I'll follow up with links to pages with duplicated and redirected content to help folks weigh the pros and cons, and also link to some of the conversations here on GitHub that are related to this topic.

[samuelsycamore]

Alright, I think we've gathered enough feedback to conclude that these docs should be duplicated across products, at least for those that aren't temporary—Base UI utility components.

The decision to redirect users to the MUI System docs for info about the Box component has been one of the most disliked changes we've made in the history of gathering docs feedback: 😅

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.