[docs-infra] mui.com/docs does not exist

[samuelsycamore]

Duplicates

• [X] I have searched the existing issues

Latest version

• [X] I have tested the latest version

Summary 💡

Now that each of MUI's products has its own documentation, we need some kind of unifying landing page to show users how to make the most of our docs to find what they need.

I'm envisioning a "Welcome" page at mui.com/docs similar to plausible.io/docs. This would be like an Overview of the Overview pages that we've been publishing for each of the products—one or two lines introducing the products, plus details about how to use the docs (search, play with codesandbox demos), how to get help, how to submit issues, etc.

Once we've established this new area of the docs, we can expand it over time to include any documentation that applies across all products. But I think it needs to start with a single landing page.

Examples 🌈

Motivation 🔦

When users click on Docs in the mui.com nav bar, it feels like it should lead to mui.com/docs rather than forcing them to choose one of our products. What if they don't know which one to select? They should be able to easily compare the products in one location without having to read multiple docs in different places.

Benchmark

• Introduction docs page https://www.apollographql.com/docs/ Apollo Docs Home
• Generic list https://www.twilio.com/docs
• Generic list https://developers.google.com/
• Generic list https://grafana.com/docs/
• Generic list https://docs.konghq.com/
• No centralized docs page https://www.hashicorp.com/products/terraform

[samuelsycamore]

@danilo-leal we've been talking about something like this for quite some time now, and I think that regardless of whether we have a true "shared" docs space, we at least need a landing page at mui.com/docs to unify all of the docs. What do you think? Also, if we move forward with this, should it look more like a marketing page, or more like a documentation page? I don't have a strong opinion but I'm leaning towards docs style, just because that's what I would expect to find on a page called mui.com/docs. cc @oliviertassinari @michaldudak @gerdadesign

[oliviertassinari]

I have added a few more benchmarks. Looking at the benchmark, here are the problems that it seems they try to solve (doesn't apply to all)

• I have too many projects to link from the home header directly. Some developers prefer to follow the docs -> product user flow rather than the product -> docs user flow, let's offer them both option.
• To help users orient themselves, could be cool when have breadcrumbs to be able to reach the root, it even helps with SEO bots to crawl.

Regarding the problem that we would solve with this page that is described "What if they don't know which one to select?", none seems to have tried to solve it. I'm not sure it should be the role of this page, but more for the marketing pages, before starting to look at the docs. A bit like https://www.hashicorp.com/why.

On a related note, maybe miss pro-code docs, MUI Core + MUI X docs, or a welcome/home docs. All of this content feels out of place:

• Changelog https://mui.com/material-ui/discover-more/changelog/
• Roadmap https://mui.com/material-ui/discover-more/roadmap/
• Vision https://mui.com/material-ui/discover-more/vision/
• Sponsors & Backers https://mui.com/material-ui/discover-more/backers/
• Design kits
• Showcase
• Versions https://mui.com/versions/

[samuelsycamore]

@oliviertassinari I agree that all of those pages would be better suited for a universal docs area.

I like the idea of a "Why" page as a supplement to my proposed "Welcome" page. The Welcome page could be the very brief, informative introduction to all products and the documentation itself, while the Why page could go into more detail from a marketing angle to persuade the reader to try our products.

After reviewing your additional benchmarks, it seems that most give this page a standard documentation style, while a few treat it more like a centralized hub/search engine. In our case I think the former is probably ideal, though we could feature the search bar prominently to encourage readers to use it/show them how.

[gerdadesign]

The goal of helping people orient themselves makes sense to me! From my newbie perspective, something that could be useful is describing who these docs are for, what to use at what stage, and outlining how they work together. Perhaps this could also give us a better place for the design resources that are hidden under deeper menus that a designer is unlikely to find. I like how many of these examples have a short, one-liner description for each product.

Here are some additional examples where I've noticed a common thread of a "Getting Started" section with more intro-friendly information and videos. Could be a useful place to house other formats of educational content as we develop that.

Looker Launch Darkly AG Grid Flutter Kendo

[danilo-leal]

Happy to see this one going on here! I personally enjoy a lot this idea. The marketing pages and the /docs space serve different purposes for me, though. The former is more about showcasing, relying on more visually appealing elements, the core features or value propositions of any given product, whereas the latter is about a bit more in-depth content.

The /docs seem like the most appropriate place to document general conventions that we print to any of our products. A few examples that come to mind:

• Composition: I can easily see this as something that Joy, Material, and Base share as a philosophy for component composition. It currently sits only on the Material docs.
  • API design approach is a very similar case.
• Vision: although it seems a bit outdated, I can also see we bringing over a few key handbook contents to this environment.
• Understanding MUI packages: definitely something that doesn't make sense being only at the Material UI docs.
• Localization: also a general MUI the company general approach.

I'm sure there might be others but this is just to illustrate. Also, something that I think we've mentioned at a meeting is the overlap of this potential general documentation space with the handbook. We should probably use the /docs space for relevant customer/user information and keep the handbook for potential/current employee relevant information.