Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Improve the Base documentation #32072

Closed
20 tasks done
michaldudak opened this issue Mar 31, 2022 · 10 comments
Closed
20 tasks done

[docs] Improve the Base documentation #32072

michaldudak opened this issue Mar 31, 2022 · 10 comments
Assignees
Labels
docs Improvements or additions to the documentation package: base-ui Specific to @mui/base

Comments

@michaldudak
Copy link
Member

michaldudak commented Mar 31, 2022

Make the Base docs comprehensive and compliant with our Style Guide (https://www.notion.so/mui-org/Style-guide-2a957a4168a54d47b14bae026d06a24b).

This is a follow-up to #31414.

Docs to review

@michaldudak michaldudak added the docs Improvements or additions to the documentation label Mar 31, 2022
@danilo-leal danilo-leal added the package: base-ui Specific to @mui/base label Mar 31, 2022
@samuelsycamore
Copy link
Member

samuelsycamore commented Apr 19, 2022

After reviewing #32364, I'm starting to notice formatting inconsistencies across these docs that I didn't catch when reviewing individually—for example, some include import code snippets and lists of Features, and others do not.

Once the individual revisions are done, I'll go back for one final pass to clean up all the little details across the board on all of these docs at once.

@samuelsycamore
Copy link
Member

Re: this comment from @michaldudak, I am going to move the Unstyled components page to the Base docs and split it up into a few "Getting started" pages.

@samuelsycamore
Copy link
Member

Template for re-formatting these pages after the first round of revisions is merged:

 ## Introduction
 ## Components API
 ### Component only content
 ## Hooks
 ### Hooks only content

@samuelsycamore
Copy link
Member

Note to self: HTML tags like <code> in the description <p> don't play nicely with search engines. These will need to be removed in the final pass.

@samuelsycamore
Copy link
Member

samuelsycamore commented May 4, 2022

Several pages such as the Switch doc mention the shared components / component / componentsProps props. The main component itself is called the "owner." We can link to more info about these props after #32562 is merged.

Similarly, we can link to the section about "Components vs hooks" from the new Usage page on the docs for components that have hook counterparts.

@samuelsycamore
Copy link
Member

ClickAwayListener needs to be reverted to its old title for SEO purposes. See: this comment

@samuelsycamore
Copy link
Member

We need to come to a consensus about styling component names, and when to refer to a specific component vs its general usage. See: this discussion

@michaldudak
Copy link
Member Author

IMO we can use just the capitalized component name without backticks unless we instruct the reader to type it or show how it should look in the code (with angle brackets) - so ButtonUnstyled and <ButtonUnstyled />.

I'd keep the backticks whenever we refer to a prop, though.

@samuelsycamore
Copy link
Member

The first pass is now complete for all Base docs! 🙌 My next task will be to create a PR that addresses formatting inconsistencies across all of these pages at once.

@samuelsycamore
Copy link
Member

There will always be further improvements to make, but I believe that the scope of this Issue has been resolved now that #33156 is merged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation package: base-ui Specific to @mui/base
Projects
None yet
Development

No branches or pull requests

3 participants