Improve DashboardLayout navigation docs #3864
Conversation
apedroferreira
changed the title
| pathname: string, | ||
| ): boolean { | ||
| if (isPageItem(navigationItem) && navigationItem.children) { | ||
| const navigationItemFullPath = `${basePath}${basePath && !navigationItem.segment ? '' : '/'}${navigationItem.segment ?? ''}`; |
There was a problem hiding this comment.
An utility for getting this path is coming in https://github.com/mui/mui-toolpad/pull/3838/files
| @@ -78,60 +93,45 @@ function DashboardLayoutNavigationActions(props) { | |||
| // Remove this const when copying and pasting into your project. | |||
| const demoWindow = window !== undefined ? window() : undefined; | |||
|
|
|||
| const popoverMenuAction = ( | |||
There was a problem hiding this comment.
I would recommend using tabs on this demo since it becomes very long to read through if expanded.
Edit: In fact, most of the demos on this page could do with separating the style, and additional components into separate files for ease of reading when expanded. You could perhaps benefit from some code sharing as well.
There was a problem hiding this comment.
You could perhaps benefit from some code sharing as well.
I'm not sure demos should do much code sharing. Ideally they're self-contained units. And as simple as possible. i.e. as simple as can be to convey the aspect that is being demoed.
There was a problem hiding this comment.
Agree with ideally them being self-contained, but perhaps we need to optimise for readability if they grow too long?
There was a problem hiding this comment.
Advantage of single file demoes is that they can be simply copy+pasted from in one action (explains some of the popularity of shadcn). Splitting them across multiple files requires more context switching on behalf of the user to get the example integrated in their own code base.
I disagree that splitting up in multiple files increases readability, to me it mostly creates extra friction to navigate the code. Instead we should think more in terms of "what can we remove from the code to get to the essence?" and focus on that to increase readability.
I believe the feature of multiple files in demoes should be used very sparingly. i.e. only when the split is mandated by the runtime (_document.js, _app.js) or perhaps to hold a demo dataset.
There was a problem hiding this comment.
I think if we're optimising for copy and paste-ability, we should ideally: advertise it, and make the demo code blocks much larger. Given the size of our demo code blocks, I think the sense that this is meant to be copy and pasted doesn't immediately come out. (For instance, https://ui.shadcn.com/blocks as a benchmark has "Copy and Paste" as a verb in the header, and a very large code block).
| Shadcn Blocks | Us |
|---|---|
 |
 |
One possible solution is to come up with a flag that can render the MUI Docs Layout with navigation hidden, so that code can be much wider.
Within the context of our docs, I think that longer code can become harder for skimming. This is my opinion, okay to drop this if single files being okay for readability is the more popular opinion 👍🏻
There was a problem hiding this comment.
About this in specific, I tried to make the preview content as short as possible while still showcasing each scenario, but when intentionally expanded I feel like it's ok for things to be longer as long as most of the code is relevant to the example.
There was a problem hiding this comment.
One possible solution is to come up with a flag that can render the MUI Docs Layout with navigation hidden, so that code can be much wider.
Yeah, seems like in some of these pages we might benefit from taking the full-width of the page as shadcn does, but so far I guess it hasn't been super necessary.
There was a problem hiding this comment.
I think if we're optimising for copy and paste-ability, we should ideally: advertise it, and make the demo code blocks much larger.
We don't optimize for copy and paste-ability in an absolute sense. Definitely not the demo previews. They are too small for most demos to achieve that, they are to help the user decide whether the particular demo from a code point of view is going to be applicable to their problem. You could say the previews are mostly optimized for scanneability, that's why they should be short, to the point and not scrollable. If such a preview is not possible, then there should be likely just no preview. The expanded version should be more optimized for copy-pasteability.
shadcn is different a different case, they basically act as a snippets library. Our demos are not snippets, we show the integration of our libraries. When I copy+paste from our docs I usually only copy portions, not the whole demo.
github-actions
bot
added
the
PR: out-of-date
…docs-improvements
github-actions
bot
removed
the
PR: out-of-date
Not sure what that means, nothing is scrollable in my screen I think... |
Improve
DashboardLayoutcomponent docs as requested in #3836Closes #3836
Docs: https://deploy-preview-3864--mui-toolpad-docs.netlify.app/toolpad/core/react-dashboard-layout
It's not as much as the "Files changed" count makes it seem - just a lot of duplicated changes there.