search

mui / mui-x

MUI X: Build complex and data-rich applications using a growing list of advanced React components, like the Data Grid, Date and Time Pickers, Charts, and more!
https://mui.com/x/
4.07k stars 1.26k forks source link

[docs] Apply style guide and consistent formatting to all X docs #5764

Open samuelsycamore opened 2 years ago

samuelsycamore commented 2 years ago

The problem

The MUI X documentation contains inconsistent formatting and grammar, and only spotty application of the company Style guide. I'd like to begin the process of editing and revising all pages, and establishing some templates for creating new pages and sections as we've done with the MUI Base and Joy UI docs.

Scope

The primary goal is consistency. I'm less concerned with adding new content except where I find 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'm sure I'll have clarifying questions along the way that I'll need help addressing.

After the first round of revisions, I'll split the pages up into groups and do a second pass to ensure consistency across the docs.

I will exclude the Introduction section which was created recently, and the API Reference sections which are a different kind of page and I think should be reviewed separately.

We also need to work on the navigation menu. We have #5565 to get the ball rolling on the date and time pickers.

This is a BIG project, so I expect it to be ongoing for quite some time. This issue is where we can keep track of the progress.

Pages

Data Grid

Date and Time Pickers

samuelsycamore commented 2 years ago

We still have not come to a consensus about the capitalization of "data grid" and "date and time pickers." I think it's very awkward (at least in US English) to apply sentence case to these names, as we often seem to do. I would much prefer to always treat them as proper nouns: Data Grid, Date and Time Pickers. The (rare) exception would be when referring to the general concept of one of these components.

oliviertassinari commented 2 years ago

We still have not come to a consensus about the capitalization of "data grid" and "date and time pickers."

Discussed a bit in https://github.com/mui/mui-x/pull/5754#discussion_r953014989.

samuelsycamore commented 1 year ago

This umbrella issue is now very outdated, but https://github.com/mui/mui-x/pull/9673 is a part of the ongoing effort here.

richbustos commented 1 year ago

Awesome! For companies I've been in where we didn't have a Voice and Tone team, I typically use this for reference:

https://developers.google.com/style/

It's awesome we are thinking this ahead of time!

samuelsycamore commented 1 year ago

Awesome! For companies I've been in where we didn't have a Voice and Tone team, I typically use this for reference:

https://developers.google.com/style/

It's awesome we are thinking this ahead of time!

@richbustos This is MUI's company style guide that I assembled based primarily on the Google docs guide (so at least some of it should look familiar) combined with Mailchimp's style guide. It also covers voice and tone as well as styling conventions for MUI products. This is what I use as the source of truth for all writing and editing. Let me know if you have any questions about it, or if you come across a situation that it doesn't cover.