Open danilo-leal opened 2 years ago
I agree with the consolidation. Just adding more info here, I would not say this is a downside but the search API won't be possible. According to our search analytics, "API" keyword is ~ 0.01%
Interesting thread. This problem has been a long time struggle. For instance, in https://github.com/mui/material-ui/commit/68e7a6d4cf6b339aebfccf4f6f141b324c3ecd03 we moved away from the grouped approach in v0 to the split approach in v1. What I would encourage is that we benchmark with all the docs that are out there, see what are UX feels awesome. Also, I'm glad we are doing this discussion on GitHub over notion 👍 .
According to our search analytics, "API" keyword is ~ 0.01%
@siriwatknp While I agree that this data is a fact, I don't think that it has any significance for a couple of reasons:
So in the end, I think that it's about the page views: GA, API pages are 14% of the of the usage.
merging the demo page with the component API page sounds like a good idea in this direction
@danilo-leal It would depend on who we ask: https://twitter.com/MUI_hq/status/1122829215961948165.
cc mui/core
I have updated the cc to include everybody. We need to take into account the needs of MUI X, to design solutions that are inclusive. And maybe we can consider two different API approaches, one for simple components like Typography and one for rich components (many different moving parts) like Tabs.
the search API won't be possible
@siriwatknp Why? From what I understand this is still possible to make the API searchable. In any case, we need the API docs to be searchable. I will veto any approaches that make, for instance, the "autocomplete renderGroup" query returns no results (or results but hidden) on Google or Algolia
I've been playing around with more complete visualizations of how that could be. Here's an example with the Text Field component, which is one that is composed of several smaller parts. We could even think of a search bar for quickly finding a given prop. We could also think of having all the tables accordion uncollapsed by default, so we don't disrupt too much today's experience. Anyway...
+1 for "uncollapsed by default" because it allows to search with Ctrl+F
We could use the right-hand side table of contents to link to individual components. IMO collapsing would not be very usable in this case.
Going back to the problem statement of this issue: "What would make traversing through the docs easier?", thoughts:
https://stripe.com/docs/stripe-js/react#element-components
This https://mui.com/api/calendar-picker/#props
would turn into something like:
is tricky. Either you need to scroll a lot of content. Or you need to find "API" in the Table Of Contents, which is never at the same place between two pages. Showing the same content but in a tab could improve the UX to find the relevant page:
We would need to give him a place in the URL, e.g. https://mui.com/components/data-grid/api/ just so that the "navigation back" action works as expected but we don't have to add it to the Google index, it can be hidden. The only blocker with this approach that I don't know how to solve is how to handle components with multiple pages, e.g. date picker, and data grid.
In https://github.com/mui/material-ui/issues/31745#issuecomment-1090984542, I think that: a. we are missing a "Component API" side nav in the left navigation because we need to be able to deep-link them in a canonical way. Some of the content in these tabs will be duplicated. b. there should be a single tab for the API because the props and styling API make sense per React component. "Text field" is a collection of React components. So structurally, I think that "merging the demo page with the component API page" would degrade the DX. However, keeping the API pages, and enhancing the demo pages to make the API content easier to consume would make sense from my perspective.
https://mantine.dev/core/menu/ is not a great execution IMHO. It fails at multiple things: a. documenting the API of the nested element, e.g. MenuItem API is documented nowhere. b. documenting the inheritance between multiple components (e.g. Input that has the same props as InputBase). c. documenting the API of hooks.
Vuetify structure to present the API of each component sounds better than what we do in production https://next.vuetifyjs.com/en/components/app-bars/#api. It gives some sense of the structure/anatomy of the component (component in the generic sense, not the React one) and how this turns into multiple React components:
This dropdown is impossible to search index, but it's immersive, and feels relatively easy to navigate. Maybe if this was backed by proper URL pages instead of popups, it could be really great.
I have one small point about the API table. I think we should consider changing from table to heading + description because on some pages, it is quite hard to read. Take a look at these examples:
One benefit is that searching method name would go directly to that section on the API page. I believe that the effort is not big, only the UI work from table to heading.
Gatsby use the heading format: https://www.gatsbyjs.com/docs/reference/config-files/gatsby-ssr/#onRenderBody
The X team uses a custom Api page to add a Slots
section
Since the Core team is starting to use the components
and componentsProps
pattern a lot, it may be interesting to unify this part as well.
I'm curious to see how to document components that also provide a hook, e.g. Autocomplete has useAutocomplete. The "Components props" tab seems to be only for React components.
https://developer.microsoft.com/en-us/fluentui#/controls/web/calendar is another example that keeps content and API on the same page. They even include related interfaces, click on See More at the bottom. For the DataGrid, I don't believe this is feasible due to the number of components to document and because they can also be divided into groups: components for editing, components for cells, components used in the filter panel, etc.
About where to put the description and type of each prop, https://www.apollographql.com/docs/react/api/react/hooks/#usequery also does a good job using the space available:
Here's more iteration on the subject, I think I've covered everyone's feedback/input:
Stripe['s] execution on the API description looks better
@oliviertassinari I do agree with the need for more horizontal space for the descriptions (https://github.com/mui/material-ui/issues/31745#issuecomment-1091568384), but how do you envisage the Stripe layout working foo props such as these?
https://mui.com/material-ui/api/button/#props
https://mui.com/x/api/date-pickers/calendar-picker/#props
(I'm sure that there are worse, but just for example).
Some of the content in these tabs will be duplicated
Could we perhaps keep the current URL structure for the API content, and iFrame it in the component pages?
Maybe #29834 could also be solved on this new api page design
We could tackle scenarios like these with the approach I suggested above:
It looks good, but I'm not sure the default value above is the worst case, and even that might struggle to fit
We could experiment using a larger horizontal space for the default value:
When there are multiple possible values for the prop, they'd stack horizontally then:
Edit Olivier: But the discussion on this moved to https://github.com/mui/material-ui/issues/34085.
It would be interesting to test this new UI with very different form of default values / description
For instance the getOpenDialogAriaText
description on https://mui.com/x/api/date-pickers/date-range-picker/ has a small function code as a default value.
And for the disableCloseOnSelect
is would we great to respect the line break (maybe this problem is on the X side though)
We'd need to play around with column spacing but it seems to work as well:
Larger spacing
Smaller spacing
Happy to see that we are making progress with shaping what a great API DX looks like for MUI in the future :). Comments on https://github.com/mui/material-ui/issues/31745#issuecomment-1098610419
Have one tab only for component and styling API (props and CSS)
Agree, I think that a change as simple as moving these
links to the top of the page instead of the bottom will already greatly improve the DX. I have caught myself multiple times scrolling to the bottom of the page to find it, it costs time.
Tweak how each prop description, default values, and optionality are displayed
Agree, that this would lead to better usage of the space.
Add Component API content in the table of contents
I personally don't buy this change if it means that developers can find all the information they need staying on this page. I think that we need as much as possible a single source of truth to keep the API in its own space and push users there. The value is that we need to maintain the API pages, I fear that duplication would:
In https://www.oreilly.com/content/the-eight-rules-of-good-documentation/ terms, It feels like a step going too far. "try to keep thinks as DRY as possible".
The new content will ultimately lead to a lot of duplicated content. The API pages will stop returning property results on searches. Or in https://documentation.divio.com/, our component pages are guides, they suggest putting API references in a clear different space.
but how do you envisage the Stripe layout working foo props such as these?
@mbrookes Then maybe on 3 different lines, It would look like this:
https://mui.com/material-ui/api/button/#props
https://mui.com/x/api/date-pickers/calendar-picker/#props
We'd need to play around with column spacing but it seems to work as well:
@danilo-leal I agree with Michal, if we were to have 3 columns and not 2, I think that having the type of the prop as its own column would work better. This is the second thing you look at when you try to provide a value as a developer, the default value comes last, after the description. We do the same information prioritization in IntelliSense:
@oliviertassinari
I have tried to answer this in https://github.com/mui/material-ui/issues/31745#issuecomment-1091440550.
Perhaps you could provide some examples? Because it doesn't appear so from the comment that you linked.
Perhaps you could provide some examples?
@mbrookes I have updated my comment to be clearer, with a visual illustration, proposing a slight modification to the design. I think that it would be great to try this change out. To see if it does deliver a superior UX as quick prototyping suggests or if it's an illusion. Considering the title of the issue: "Unify component demo page with the API page", then it could be considered a bit off-topic.
Going back to the issue itself, the more we move forward with this exploration, the more it feels that unifying the demo pages with the API strictly speaking would be a step backward.
So maybe we should rename the issue to something like "Improve API access from demo pages", it seems to be the underlying DX pain point we try to solve. Maybe moving the API links to the top of the page rather than the bottom is THE answer. In any case, we can keep this issue focused on the problem, rather than one solution.
maybe we should rename the issue to something like "Improve API access from demo pages"
👍 👍 👍
For me this problem is the main issue we currently have with the doc on X, the props table are totally impossible to read: #34085. I think we have a few improvements we can make to this table without doing any big structural change to the doc.
I had a look at how our main competitors our displaying their props table.
Each competitor has 2 examples, one on my QHD screen (2471px of content width) and one on my QHD screen split in half (1227px of content width).
For me this problem is the main issue we currently have with the doc on X, the props table are totally impossible to read.
@flaviendelangle Did you mean to post this on #34085 (API page overflow)? We are talking about a different problem on this issue (the user journeys for the developers to consume the reference data).
For me this issue was also talking about the layout of the prop table
https://github.com/mui/material-ui/issues/31745#issuecomment-1091440550
https://github.com/mui/material-ui/issues/31745#issuecomment-1118958353
Motivation
This proposal is all about the speed of navigation. What would make traversing through the docs easier? Besides improving the search experience, which we did a few months ago, merging the demo page with the component API page sounds like a good idea in this direction. For me, personally, having them separated breaks my navigation flow a bit. Additionally, the Component API folder on the side nav is sorted alphabetically whereas the Component folder is not (sorted through a specific order), which frequently gets me confused.
I also think that having everything under the same "umbrella" would facilitate learning components that are made out of several smaller ones — Text Field might be the most illustrative of this.
How this could look
Here's the first design to kick this off.
Down sides
Is there any we should consider and bring to light? What would we lose or run the risk of making worse if we moved forward with this? I can't see anything right now. I remember we talked about that not even from an SEO standpoint this would be bad. So, what else?
Related issue
The look & feel of the API table: #34085.
cc @mui/maintainers