search

mui / mui-toolpad

Toolpad Studio: Low-code admin builder. Open-source and powered by MUI.
https://mui.com/toolpad/
MIT License
815 stars 206 forks source link

[docs] Toolpad docs part 1 #859

Closed bytasv closed 1 year ago

bytasv commented 1 year ago

Partial implementation for #834 Preview: https://deploy-preview-859--mui-toolpad-docs.netlify.app/toolpad/getting-started/overview/

  1. Started working on docs according to notion page structure - got Introduction and Quickstart pages
  2. Merged Setup steps into Quickstart as that was basically one paragraph on it's own page
  3. Added step-by-step guide both to build first app and to deploy it
  4. Connecting to data sources - Connections, Query, Fetch, Function ✅
  5. Data binding section ✅
render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-859.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-cc4am2b19n0agdht37vg.

prakhargupta1 commented 1 year ago

A couple of suggestions for consideration. Should we replace:

  1. Toolpad app with Toolpad
  2. Component's library with Component drawer
  3. Application editor with Canvas
  4. Properties editor with Properties pane or right pane
  5. Instance editor with left pane

based on: -single word > two words -Along with the name, if we could help users visualize then it would be better

Janpot commented 1 year ago
  1. Instance editor with left pane

alternatively:

bytasv commented 1 year ago

@oliviertassinari

I'm not sure about how much work this represents. If it's a big effort, I think that we should change this to: "One step toward https://github.com/mui/mui-toolpad/issues/834". So we can have small PRs that we merge incrementally.

I can definitely do that, I'm just not sure how fast we can merge this one then so I wouldn't blocked to open new ones. Or maybe this can be merged and still kept for feedback that I could deliver in a follow up PRs?

Regarding who should review this PR, would it make sense to have, Prakhar & Jan for the product side and maybe Sam for the technical writing dimension in the first few PRs to the point where most of the best practices have been shared?

Yeah, I think it makes sense, in general the more people look the better as I might have missed some things, might have explained something how I understand but maybe it's not how it actually is, etc...

@prakhargupta1

Component's library with Component drawer

I'm wondering if we are sure that the UI for that will not change? Are we going to keep using "drawer" in the future as well? I was thinking about more "universal" name that would not depend on the implementation 🤔

For no.5 - I like Jan's proposal for "Explorer" or basically looking for analogy in other products. Quick search gave me this:

image

Seems that "explorer" in VS code refers only to files explorer, in our case it might be instance explorer (short version just "explorer") but maybe we should use more generic one "Sidebar"? 🤔

I see following options that could be used:

  1. Left pane and Right pane
  2. Explorer (left) and Properties (right)
  3. Left sidebar and Right sidebar (this is maybe bit more explicit as being on the "side" compared to pane 🤔 )

More examples:

xcode: image

one more for xcode (navigator and inspector sounds nice as well) image

It also got me thinking about this

Application editor with Canvas

Seems that Canvas isn't commonly used, so maybe just keep Editor?

Janpot commented 1 year ago

The Toolpad docs are very image heavy. This is a difference from the core docs. I see a few issues that could come up:

  1. Linting: There's no automated build-time check that verifies that a referenced image exists. This could lead to broken images.
  2. Cache busting: All screenshots are stored in the static folder and referred to by url. They are not content addressable and thus we'll have to resort to either not caching them client-side, or manually busting the cache by renaming the images when we update them.
  3. Image optimization: There is no automatic image optimization step, so every time an image is added/updated it will have to be run manually through an optimizer.
  4. Layout shift: It doesn't look like including the image in the markdown adds width and height to the markup. I saw text being pushed down while loading. Scroll restoration seemed to work with images coming in, in my limited testing.

From an ideal DX point of view, a build step could extract images, optimize them, create multiple versions for them (size/quality), add hashes to their names, measure and reference them using something like the next/image component. It's clear that there would a build performance trade-off to be made here, but maybe there are ways to omit unchanged images from this process.

Or maybe it needs a CMS?

@oliviertassinari Has there already been any thought about this problem for the core docs

Janpot commented 1 year ago

@oliviertassinari I'm moving the discussion to the docs infra notion space https://www.notion.so/mui-org/Images-solution-30e78dbf24744ed5b570027656139092

render[bot] commented 1 year ago

Your Render PR Server URL is https://toolpad-pr-859.onrender.com.

Follow its progress at https://dashboard.render.com/web/srv-ccbh0nha6gdmq3q92kpg.

bytasv commented 1 year ago

@mui/toolpad I think I've managed to address all comments, please check again when you have time.

For now I've set a few things aside that I'm planning to address in a follow up PRs:

bytasv commented 1 year ago

Review for connections.md. There's a lot of unnecessary formatting here. I tried to remove most of it but there are sections where it would be unwieldy for me to suggest it all. Mainly words in bold and lots of indentation that seems out of place to me.

Our docs should use "you" rather than "we" because "we" aren't the ones using the app, after all. :)

This page also includes several nested lists which get cumbersome. I tried to replace these with a hierarchy of headers.

I'll follow up with reviews for the other pages.

@samuelsycamore I'm updating all other pages as per your comments, hopefully you'll have less to add after that :)

edit: I removed most of bold words and also changed all we to you

bytasv commented 1 year ago

I finally managed to update all images and fix tags that were used to insert them. They do look much better now.

@samuelsycamore are you still going to review some of the pages or is this good to be merged? In case you want to still review some pages but might not have time to do it quickly would you be fine with merging this and then I could manually apply suggested content changes?

samuelsycamore commented 1 year ago

@samuelsycamore are you still going to review some of the pages or is this good to be merged?

@bytasv I'm sorry I haven't had more time to devote here! I can do a final pass on the remaining docs and have suggestions for you by my EOD Monday.

bytasv commented 1 year ago

Hey @samuelsycamore is this good to be merged?

samuelsycamore commented 1 year ago

@bytasv I'm good to merge this as it is, mainly because this PR has gotten massive and I don't want to add 100 more comments to it! 😅 I would still like to review the "Connecting to datasources" pages, but I can open separate PRs and tackle them one by one once this is wrapped up here.

bytasv commented 1 year ago

Thanks @samuelsycamore ! See what's the easiest way for you to deliver feedback, you can comment on this PR or open new one, lemme know if I can assist somehow