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][base-ui] Revise the structure of the Component docs #38529

Merged
merged 1 commit into from
Aug 22, 2023
Merged

[docs][base-ui] Revise the structure of the Component docs #38529

merged 1 commit into from
Aug 22, 2023

Conversation

samuelsycamore
Copy link
Contributor

@samuelsycamore samuelsycamore commented Aug 17, 2023

In the current version of the Base UI docs, the headers are structured like this:

## Introduction
## Component
### Usage
### Basics
### Anatomy
### Custom structure
## Hook
### etc.

Preview: https://deploy-preview-38529--material-ui.netlify.app/base-ui/react-switch/

In practice, there's a lot of overlap between the Introduction, Usage, and Basics sections, and some of the docs have redundant content repeated in each—particularly since we added the Intro playgrounds.

This PR:

  • condenses Usage and Basics in to one section called Usage
  • removes most of the boilerplate Basics code (leaving only the import, as we've done in the Joy UI docs)
  • removes Usage/Basics content where it's just repeating the Introduction

I also couldn't resist doing some copyediting, mostly to the Autocomplete page.

Before:
Screenshot 2023-08-17 at 6 13 01 PM

After:
Screenshot 2023-08-17 at 6 12 34 PM

Right now this PR only involves a few of the pages, because I want to make sure we agree on the updated format before applying it to all others. I tried to take a sample of several different kinds of pages to see how the new format works. There may be other kinks to work out in the next pass, but I think this is good way to proceed.

@samuelsycamore samuelsycamore added docs Improvements or additions to the documentation package: base-ui Specific to @mui/base labels Aug 17, 2023
Copy link
Contributor

@danilo-leal danilo-leal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really like this new structure! Makes a ton of sense to me 🤙

@siriwatknp siriwatknp merged commit 792a065 into mui:master Aug 22, 2023
@samuelsycamore
Copy link
Contributor Author

Ah shoot @siriwatknp I should have marked this as a "DO NOT MERGE"—I'd like to wait to apply the updated format to all pages before this PR goes out. Can we revert it?

@oliviertassinari
Copy link
Member

oliviertassinari commented Aug 23, 2023

I would be in favor of always having the author merge PRs, unless the changes are obvious or the PR got forgotten. Two other cases: #38393, #38241 (as I understood it, Rich was a bit surprised) where I feel merging wasn't ideal.

@siriwatknp
Copy link
Member

Ah shoot @siriwatknp I should have marked this as a "DO NOT MERGE"—I'd like to wait to apply the updated format to all pages before this PR goes out. Can we revert it?

Oops! sorry.

@samuelsycamore
Copy link
Contributor Author

No worries @siriwatknp! It's not a big deal to have this merged early—I'm sure we'll still do a couple more drafts of these docs before the stable release.

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

Successfully merging this pull request may close these issues.

5 participants