[docs] Duplicated pages for Base components in Material UI are outdated

[samuelsycamore]

The problem

The Material UI package contains some utility components that it shares in common with MUI Base.

These components are the exact same—they're imported directly from the Base package into Material UI with nothing added.

• Textarea Autosize https://mui.com/base/react-textarea-autosize/ vs. https://mui.com/material-ui/react-textarea-autosize/
• Click-Away Listener
• Portal
• No-SSR

Am I missing any others?

Right now, the most up-to-date and comprehensive version of the docs on these duplicated components resides within MUI Base. Additionally, the Material UI versions don't offer much of an explanation regarding what these components are, what Base is, and how these components compare/contrast with their Base counterparts.

This presents a great opportunity to educate Material UI users about Base and encourage them to use the Base versions instead of the Material UI versions going forward.

The proposed solution

After talking it over with @oliviertassinari, we were leaning on:

• Pages for Material UI components that are exact duplicates should be removed and redirected to their corresponding Base pages
  • The Base pages should include a callout explaining their presence in the Material UI package
  • We should merge the content of the two versions to only keep the best of them.
• The Material UI versions of these components should probably be deprecated in a future major version (v6 or v7)

cc @michaldudak I'd love to hear what you think about this. I think it's the best option to avoid duplicating this content on both sides.

[michaldudak]

What do you think about having a very short description on each of these pages saying that this component is a part of MUI Base and it's documented there (and it's reexported from Material UI just for convenience)?
Redirecting to Base docs directly may confuse people (especially if they don't notice the product context changed, they may be surprised to see much fewer components in the menu.

[samuelsycamore]

What do you think about having a very short description on each of these pages saying that this component is a part of MUI Base and it's documented there (and it's reexported from Material UI just for convenience)?

@michaldudak In this case, would we remove all other content from the Material UI version of the page? I think this makes sense as a stop-gap measure on the way to deprecation in the future.

[michaldudak]

In this case, would we remove all other content from the Material UI version of the page? I think this makes sense as a stop-gap measure on the way to deprecation in the future.

Yes, I think this is my preferred option.

[samuelsycamore]

Cool, I'm happy to move forward with that plan as long as @oliviertassinari doesn't have any objections.

[oliviertassinari]

Redirecting to Base docs directly may confuse people

@michaldudak to be clear on this one. The idea was to remove these components from the left side nav on Material UI. The "redirection" is about the 301 that is necessary to add to not break SEO. So I believe that there won't be the confusion of a magic product change.

having a very short description on each of these pages saying that this component is a part of MUI Base and it's documented there (and it's reexported from Material UI just for convenience)?

We discussed this option. My concern is about the experience when developers search on Google and with Algolia. They will need an extra click when they land on the "wrong" page but I agree it better educates developers.

In this case, would we remove all other content from the Material UI version of the page? I think this makes sense as a stop-gap measure on the way to deprecation in the future.

No objections. I like that we could encourage to import from @mui/base directly on these pages. The strategical move being that we would teach developers how they can keep using MUI when they don't want to use Material UI anymore.

[samuelsycamore]

Alright, this sounds like the best course of action to me:

• Make the Base docs the single source of truth about these components.
• Replace content on the Material UI pages with info about Base, point users to those docs, and mention that the Material UI versions of the components will be deprecated in the future.
• When these components are finally deprecated, then we can remove and redirect the Material UI pages.

Does that work?