[RFC] Different way for showing the API references

[mnajdova]

With the growing number of components, demos, and hooks we are introducing, it starts to become harder to get the API information for the different components and hooks from the demos pages. We are investigating different ways how we can improve this #35938. These are the options we currently have:

Option 1: Keep things as they are

Each page will have the API section as the last, where developers can find links to all components & hooks documented on the page. For e.g.: https://mui.com/base/react-tabs/#api

Pros:

• Developers are already used to this structure
• We won’t spend any time on the problem, which means that this time can be spent on other topics.

Cons:

• The user journey is not great - usually, developers need to scroll (either the page or the table of content) in order to get to this section
• For the MUI Base demo pages, where we document both components and hooks, the list of API pages can grow significantly

Option 2: Add tabs for each section and place content in the tab panels.

Each tab in its content will list sections for all components and hooks API information (the content is the same as in the current API pages. This is a POC of how this can look like: https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/

Pros:

• The API information section is available for a click regardless of the scroll of the page
• The content of the page is immediately accessible, for e.g. developers can use CMD/CTRL + F to search for a specific prop

Cons:

• For some pages, the number of components/hooks means that people need to use the table of content in order to get to the specific component/hook they are interested in, take a look at: https://deploy-preview-35938--material-ui.netlify.app/base/react-tabs/?docsTab=component-api#tabs-list-unstyled
• There is no clear separation of the content between each module, you can't scroll too fast.

Option 3: Add tabs for each section containing links to the API pages

Add tabs for the demos, components’ API, and hooks API at the top of the page, where each tab will host the links to the different API pages. This is a POC of how this can look like: https://deploy-preview-36178--material-ui.netlify.app/base/react-tabs/

Pros:

• It minimizes the overall effort to show the API of a given module. (e.g. the API information section is available for a click regardless of the scroll of the page, you don't need to move your attention away from the body to the TOCs, which on a large screen is far)
• Simpler to be implemented compared to Option 2

Cons:

• The content of the API pages is not immediately Cmd+F searchable (it's one more click away than option 2)
• You can't see multiple exported modules that relate to the same component on the same page.

---

Which option would you prefer and why? Use the up button to leave your vote:

[stamahto]

I personally liked style 3, I tried the demos and searching for a specific prop was the fastest in 3rd option.
It's like I have to scroll less and therefore have to read less.
Thank you for this idea and demo 👍

[RiverTwilight]

I prefer option 2. Compared with 3, it won't increase page's height too much, so we can scroll to the part we want quickly.

[stephzero1]

2° style is the best for me

[felix-bohlin]

2 or 3. They are both an improvment.

• What I like about option 2 is the fact that you don't jump away to the API section in the menu. It's nice to stay in the same context.
• What I like about option 3 is the fact that you don't get everything at once and can CTRL + F stuff easier.

I don't feel strongly about 2 or 3 as I think anyone can adapt to either quite easily.

[nkalpakis21]

2 or 3. I prefer 2 since everything looks to be in one place.

[samuelsycamore]

I think 2 is the clear winner personally. The Table of Contents actually looks really clean and easy to use here, so I don't see any cons. With 3 we still have the fundamental problem of users getting frustrated when they land on the wrong page.

All that said—if there's one thing we've learned from the current implementation of the Component and API pages, it's that we need to make the tabs as obvious and eye-catching as possible. If this Demos callout isn't enough for some users to find what they need (and it remains a common complaint in our doc feedback even after bumping this to the top of the page), then I fear that users aren't going to see the tabs unless they really stand out on the page.

[tomzacchia]

I like option 2 but think the nav could be placed before the main content, at first it wasn't obvious that I could navigate using the side menu to different parts of the doc for every tab.

[thevipinmishra]

Option 2 looks like the winner to me!

[sebammon]

Option 2 is great, it has all the relevant information you need without redirection plus you can use CTRL + F. However I find the "Demo, Component, Hook" tab is easy to miss (at least the first time you see it)

[kriskw1999]

Third is better for the developers.
I imagine the following scenario:

• a user is using a component A and is interested on the api documentation
• he enters in the api and sees immediately the link to A component without searching it in the page

In this way the developer does not take a look on components on which he is not interested and can focus on relevant information.

But I have a question, if there is a page where the API section is single, in the third solution I see a single link or there is the possibility to see the full page without the link?

[kxseilerjo]

Personally I think there is a strong case for combining options 2 and 3. In my eyes there is certainly a benefit to having all relevant information available in the same document but also to being able to quickly navigate to the dedicated docs page with just the info you need if you already what that is. If option 2 is implemented, option 3 seems like such low hanging fruit that it would almost be a crime to omit it.