[docs][joy-ui] Enforce standard structure, style, and grammar across all docs

[samuelsycamore]

The problem

The Joy UI documentation currently contains inconsistent grammar, style, voice, and formatting throughout. It's important to address this non-technical debt (prose debt? 😅) as we continue to grow this library and prepare for the stable release.

I would like to audit and revise each existing page individually to apply our company style guide and best practices for writing documentation.

Scope

The primary goal is consistency. I'm less concerned with adding new content except where we find major gaps that need to be covered.

I intend to review each page individually. Most pages will get their own PR, but some may be grouped together if the edits are minimal. I'll edit as needed for grammar, style, page formatting, content clarity, and completeness.

I don't intend to do any restructuring of the doc nav menu here.

This is a big project, so I expect it to be ongoing for a while. This issue is where we can keep track of the progress.

Pages

• Getting started
  • [x] Overview - #34087
  • [x] Installation - #34168
  • [x] Usage - #34183
  • [x] Tutorial - #34569
  • MAIN FEATURES
  • [x] Global variants - #34595
  • [x] Color inversion
  • [x] Automatic adjustment - #34614
  • [x] Dark mode optimization - #34613
• Components
  • INPUTS
  • [ ] Autocomplete
  • [x] Button - #35737
  • [ ] Button Group
  • [x] Checkbox - #35817
  • [x] Input - #35970
  • [x] Radio Button - #35893
  • [ ] Select
  • [ ] Slider
  • [ ] Switch
  • [ ] Textarea
  • [ ] Text Field
  • [ ] Toggle Button Group
  • DATA DISPLAY
  • [x] Aspect Ratio - #34858
  • [x] Avatar - #35152
  • [x] Badge - #35199
  • [ ] Chip
  • [ ] Divider
  • [x] List - #36324
  • [ ] Table
  • [ ] Tooltip
  • [x] Typography - #35868
  • FEEDBACK
  • [x] Alert - #34838
  • [x] Circular progress - #36126
  • [ ] Linear Progress
  • [ ] Modal
  • [ ] Skeleton
  • [ ] Snackbar
  • SURFACES
  • [ ] Accordion
  • [x] Card - #35745
  • [ ] Sheet
  • NAVIGATION
  • [x] Breadcrumbs - #35292
  • [x] Drawer - https://github.com/mui/material-ui/pull/38988
  • [x] Link - #37829
  • [ ] Menu
  • [ ] Tabs
  • LAYOUT
  • [ ] Grid
  • [ ] Stack
  • UTILS
  • [ ] CSS Baseline
• Customization
  • [ ] Approaches
  • THEME
  • [x] Colors - https://github.com/mui/material-ui/pull/38402
  • [ ] Shadow
  • [x] Typography - https://github.com/mui/material-ui/pull/38285
  • [ ] Components
  • GUIDES
  • [ ] Dark mode
  • [ ] Using CSS variables
  • [ ] Creating themed components
  • [x] Overriding the component structure
  • TOOLS
  • [x] Default theme viewer - https://github.com/mui/material-ui/pull/39049
  • [ ] Theme builder
• INTEGRATIONS
  • [x] Next.js App Router
  • [ ] Usage with Material UI
  • [ ] Using other icon libraries
• MIGRATION
  • [x] Migrating the default theme

[siriwatknp]

Thanks! @samuelsycamore.

[mbrookes]

Thanks @samuelsycamore, I appreciate the thorough response to my request! Feel free to let me know where you'd like a second review,.

[samuelsycamore]

This is the page structure/template that I plan to use going forward:

# {{Component Name}}

## Introduction

## Basics

- import
- basic usage description and demo

## Customization

### Variants

### Sizes

### Colors

### Decorators

### etc.

## Usage with {{Other Component}}

### Details on specific usage

## Common examples

### Example 

### etc.

## Accessibility

## Anatomy

[samuelsycamore]

I'm placing this issue on hold for now as the Core team shifts focus to Material UI for the first half of 2024.

[github-actions[bot]]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue. Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.