Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
4 tasks
oliviertassinari opened this issue Dec 2, 2023 · 0 comments
Open
4 tasks

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

oliviertassinari opened this issue Dec 2, 2023 · 0 comments
Assignees
Labels
docs Improvements or additions to the documentation package: material-ui Specific to @mui/material priority: important This change can make a difference

Comments

@oliviertassinari
Copy link
Member

oliviertassinari commented Dec 2, 2023

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.

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.

@oliviertassinari oliviertassinari added docs Improvements or additions to the documentation package: material-ui Specific to @mui/material status: waiting for maintainer These issues haven't been looked at yet by a maintainer labels Dec 2, 2023
@samuelsycamore samuelsycamore removed the status: waiting for maintainer These issues haven't been looked at yet by a maintainer label Dec 11, 2023
@danilo-leal danilo-leal changed the title [docs] Redo integration docs pages [material-ui][docs] Redo integration docs pages Jan 3, 2024
@oliviertassinari oliviertassinari added the priority: important This change can make a difference label May 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation package: material-ui Specific to @mui/material priority: important This change can make a difference
Projects
Status: Backlog
Development

No branches or pull requests

2 participants