[docs] Revise Joy UI "Radio" page

[DevinCLane]

part of #33998

WIP

Started to work on the Title section as well as the introduction. Mainly working on grammar, style, consistency.

Feel free to let me know any comments you might have.

Thanks!

[mui-bot]

Netlify deploy preview

• docs/data/joy/components/radio-button/radio-button.md

Bundle size report

No bundle size changes

Generated by 🚫 dangerJS against c893989

[mapache-salvaje]

Thanks for taking this on @DevinCLane !! Holler at me when you're ready for a review!

[DevinCLane]

Hey @samuelsycamore, we're ready for a review.

"Anatomy" section could use a look.

I used the Radio Group page from Material UI to match for consistency. Also read through your work on Checkbox (#35817) for inspiration.

Thanks!

[mapache-salvaje]

This is a great start! The content you've added is definitely an improvement over the existing page.

Before I jump into a line-by-line reading, let's talk about the big picture. Peep the h2 and h3 headers listed in the right-side table of contents in the Alert component doc, for example—this one serves as a good template for how all of these pages should be structured. At a minimum we should see h2s for Introduction, Basics, Customization, and Anatomy (in that order). The Radio page also includes sections for Common examples and Accessibility, which are h2s that are frequently (but not always) found on these pages.

In the next draft, try to match this structure as closely as possible. Don't be afraid to do some heavy rearranging and rewriting as needed.

Finally, I would caution against leaning too heavily on the Material UI docs for reference—it can be helpful in some cases, but these docs have never seen the hand of an editor before, so many are in various states of disorder/disarray by my standards. 😅 The best reference would be the other Joy UI doc pages that have already been revised.

[DevinCLane]

Got it, will rearrange and rewrite as needed to fit that structure. And I will divest from the Material UI as a style guide and look more to the other edited Joy UI docs to match the voice.

[DevinCLane]

I rearranged things to better match the structure--let me know if this works or if I've missed anything!

[DevinCLane]

@samuelsycamore following up here to see if the updated structure works!

[mapache-salvaje]

Sorry for the delay on my end @DevinCLane ! Structure is looking good. In the next pass, try to make all of the component names consistent. Our engineers use various style patterns:

• Form Control
• FormControl
• FormControl
• form control
• etc.

Only the first one is correct.

[DevinCLane]

Made a pass at consistent component formatting.

@samuelsycamore I imagine you might have some thoughts on when a component such as Radio needs to be capitalized "Radio" vs when we are talking about "a radio button". Did my best to stay consistent here: when it felt like we were talking about the concept of a general radio button, left uncapitalized; when it seemed we were discussing the Radio component, capitalized it.

[mapache-salvaje]

I apologize @DevinCLane, I don't think I ever shared the Style Guide with you! I definitely have some thoughts on this topic. 😁 You can find those in the Style Conventions for MUI Components doc.

[DevinCLane]

@samuelsycamore: read through the style guide and made some updates. Couldn't seem to find a mention of how to style props and CSS properties, I figured that was in line with referring to code so I left them with backticks.

Let me know what you think!

[mapache-salvaje]

Thanks @DevinCLane ! You picked a doozy of a doc to tackle! Let me know if you have any questions about my edits here.

[DevinCLane]

Great, thanks for the edits. Will take a look, work on implementing, and let you know if I have any questions.

[DevinCLane]

@samuelsycamore

• Applied your line edits
• Reordered variants, breaking them into their own sections, added demos

The preexisting demos were still written in .js and therefore don't have their .tsx.preview files to match the format you have in the updated Joy Badge docs, for example. I imagine we might want to change these to match?

Looking forward to the comments, cheers!

[siriwatknp]

👍 This looks good to me, thanks for the improvements!

[mapache-salvaje]

Great job @DevinCLane ! I just made a few tiny copy edits to wrap things up here. Thanks for your patience!