[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
  • Overview - [docs] Revise Joy UI "Overview" page copy #34087
  • Installation - [docs] Standardize all MUI Core "Installation" pages #34168
  • Usage - [docs] Standardize all MUI Core "Usage" pages #34183
  • Tutorial - [docs] Revise and expand Joy UI "Tutorial" doc #34569
  • MAIN FEATURES
    • Global variants - [docs] Revise the Joy UI "Global variants" page #34595
    • Color inversion
    • Automatic adjustment - [docs] Revise the Joy UI "Automatic adjustment" page #34614
    • Dark mode optimization - [docs] Revise (and rename?) the Joy UI "Perfect dark mode" page #34613
• Components
  • INPUTS
    • Autocomplete
    • Button - [docs] Revise and expand Joy UI Button doc #35737
    • Button Group
    • Checkbox - [docs] Revise and expand Joy UI Checkbox doc #35817
    • Input - [docs] Revise Joy UI "Input" page  #35970
    • Radio Button - [docs] Revise Joy UI "Radio" page #35893
    • Select
    • Slider
    • Switch
    • Textarea
    • Text Field
    • Toggle Button Group
  • DATA DISPLAY
    • Aspect Ratio - [docs] Revise the Joy UI "Aspect Ratio" page #34858
    • Avatar - [docs] Revise the Joy UI "Avatar" component page #35152
    • Badge - [docs] Revise and expand the Joy UI "Badge" page #35199
    • Chip
    • Divider
    • List - [joy-ui][docs] Revise the Lists page #36324
    • Table
    • Tooltip
    • Typography - [docs] Revise Joy UI "Typography" page #35868
  • FEEDBACK
    • Alert - [docs] Revise and expand Joy UI "Alert" page #34838
    • Circular progress - [docs] Revise Joy UI "Circular Progress" page #36126
    • Linear Progress
    • Modal
    • Skeleton
    • Snackbar
  • SURFACES
    • Accordion
    • Card - [docs] Revise and expand the Joy UI Card page #35745
    • Sheet
  • NAVIGATION
    • Breadcrumbs - [docs] Revise and expand Joy UI "Breadcrumbs" page #35292
    • Drawer - [docs][joy-ui] Revise the Drawer page #38988
    • Link - [docs][joy] Revise the Joy UI Link page #37829
    • Menu
    • Tabs
  • LAYOUT
    • Grid
    • Stack
  • UTILS
    • CSS Baseline
• Customization
  • Approaches
  • THEME
    • Colors - [docs][joy-ui] Revise the theme color page #38402
    • Shadow
    • Typography - [docs][joy-ui] Revise the theme typography page #38285
    • Components
  • GUIDES
    • Dark mode
    • Using CSS variables
    • Creating themed components
    • Overriding the component structure
  • TOOLS
    • Default theme viewer - [docs] Improve the default theme viewer design #39049
    • Theme builder
• INTEGRATIONS
  • Next.js App Router
  • Usage with Material UI
  • Using other icon libraries
• MIGRATION
  • 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]

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.