search

mui / material-ui

Material UI: Comprehensive React component library that implements Google's Material Design. Free forever.
https://mui.com/material-ui/
MIT License
94.02k stars 32.3k forks source link

[material-ui][docs] Redo integration docs pages #40062

Open oliviertassinari opened 11 months ago

oliviertassinari commented 11 months ago

Problems 💡

I think we must rework the whole section of https://mui.com/material-ui/getting-started/example-projects/. It's not great:

  1. "Example projects" as a header doesn't make sense to me. These are more specific
  2. We are missing integration examples
  3. We don't have a detailed guide on how to integrate with each. If you have an existing project, you have to go to the examples to figure it out by yourself, this sucks.
  4. https://mui.com/material-ui/getting-started/usage/#globals this is mostly about "Installation". You have to pick how you want to install the library, but overall, it feels backward.

Proposal

  1. Create a new Integration page alongside https://mui.com/material-ui/getting-started/example-projects/ under the getting started area of the docs. Cover all the integrations with the framework that are relevant. We have another Integration section in https://mui.com/material-ui/integrations/routing/ but are a bit different, you don't need those to get started.

  2. Have an example and a step-by-step guide on how to configure each integration. Mantine is one that embodies the best proposal, e.g. https://mantine.dev/guides/remix/. https://tailwindcss.com/docs/installation/framework-guides is nice but is missing examples. This is also great when you start and need to rely on two integrations, e.g. Next.js + Tailwind CSS.

  3. Move https://mui.com/material-ui/integrations/nextjs/ to be hosted under 1. since it's required to get started. Same for https://mui.com/joy-ui/integrations/next-js-app-router/.

  4. Add the missing framework integration

    • [ ] Astro
    • [ ] Laravel
    • [ ] Django
    • [ ] etc.

  5. In https://mui.com/material-ui/getting-started/example-projects/, I think we should:

    i. link the showcase too. The whole point of this page is to give people examples they can get inspiration from. ii. update "Official examples" to remove this section or point to page 1, since people might land on this page without having seen the integration yets. iv. add cool project examples that we can find, assuming that 6.i. isn't enough. Like I could see how having a link to the showcase with open-source project would do the job well.

  6. the React-admin and Refine examples should be moved under a general integration docs area https://mui.com/material-ui/integrations/routing/ since they are not needed to get started, it feels more common to add them to an existing project.

  7. That general integration docs area should also reference the framework integration so they can be seen as a catalog of all the integrations available, useful as a marketing asset to convince developers.

Motivation 🔦

Improve the onboarding experience, which is critical in the journey of developers.

alelthomas commented 2 weeks ago

It's 3 pages that we need to re-structure:

oliviertassinari commented 2 weeks ago

@alelthomas Thought on this:

Example projects

"Integrations" might not be clear enough about what this is about. There could be different types of integrations. Since it's more about frameworks and installation, maybe "Framework setup" would be clearer?

Related projects

We created this section for things that we want people to be able to find with a search (Google, Algolia). It's about supplementary content that we can't quite add anywhere else. So for this reason, I think it should be located under "Discover more", far in the side nav, hard to find (so other stuff are easy to find).

On renaming the page "Community projects", we could have our own stuff in there too, e.g. Toolpad and will have other community project on other pages, where relevant, so the title feels more about "Supplementary projects".

For example, this move https://github.com/mui/material-ui/pull/44191/files#diff-be4ae77f71d791c8d765b321ebe72e65f4fe7893fea1fad0f46985e2fe25dfddR30 looks backward, I think we should move this to be under "Getting started", not under "Discover more".

Showcase.

It feels like this can be perfect linked in the header navigation, and not in the side nav (we did that back then as we didn't have time), it's not really about the docs. Tweaking Next.js, TypeScript, Bootstrap, Tailwind CSS, Radix it feels like this would be right:

SCR-20241103-qmrr SCR-20241103-qmmg SCR-20241103-qmzf SCR-20241103-qnom SCR-20241103-qoaw

So overall, it could look like this (notice the pages deleted or moved):

SCR-20241103-qzsl
samuelsycamore commented 2 weeks ago

For example, this move https://github.com/mui/material-ui/pull/44191/files#diff-be4ae77f71d791c8d765b321ebe72e65f4fe7893fea1fad0f46985e2fe25dfddR30 looks backward, I think we should move this to be under "Getting started", not under "Discover more".

I don't think it makes much sense to list third-party projects in our Getting Started sequence—do we really want to redirect users outside of our product suite while reading the first few pages in the docs? This section of the docs should be super tight and focused solely on the new user's immediate needs. I think any resources we link at this stage in the user journey should come from our own docs. We just have no control over the experience or the quality of those projects (aside from vetting them before linking, of course), and I think they're tangential to the needs of most users.

oliviertassinari commented 4 days ago

This section of the docs should be super tight and focused solely on the new user's immediate needs.

@samuelsycamore Agree.

The way I see this, it's equivalent to https://react.dev/learn/start-a-new-react-project#production-grade-react-frameworks. A developer should have all he needs to be successful in using the project. I think success is about having the time from "I have a pain" -> "I have something that seems to be set up and work I can work with" that is lower than all the competing UI libraries or that is as low as physically possible. I don't see a lot of differences between teaching people how to set up Material UI with Remix and with Refine, it feels close to being the same thing.