search

mui / mui-public

The public mono-repository of MUI (as an organization), see mui/mui-private for the opposite.
80 stars 16 forks source link

[docs] Reference all function calls with `()` #218

Open oliviertassinari opened 1 month ago

oliviertassinari commented 1 month ago

Steps to reproduce

On https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault, all function references have (), this seems to be clearer when reading the docs.

For example:

SCR-20241022-nlcl

https://deploy-preview-44139--material-ui.netlify.app/material-ui/customization/dark-mode/#styling-in-dark-mode

vs. it could be:

SCR-20241022-nlhb

what if we were to do this change?

Search keywords:

samuelsycamore commented 1 month ago

I think this is a great idea—similar to the use to <ComponentCase /> which has been useful when revising the X docs, it's really nice to have an immediate visual cue for what kind of code this is.

oliviertassinari commented 1 month ago

I think this is a great idea—similar to the

@samuelsycamore Should we add this to the style guide like https://www.notion.so/mui-org/Writing-style-guide-2a957a4168a54d47b14bae026d06a24b#25c93204591e4d3da592abea674515fa?

Off topic

similar to the use to <ComponentCase />

Historicaly, I think we were less on <ComponentCase /> and more on ComponentCase because if it's PascalCase, it can almost only be a component and < /> slow down? the reading flow. Now, happy either way. I see that Base UI uses a mix of things e.g. https://base-ui.com/components/react-alert-dialog/

So I guess to standardize on a single approach? If one is better, it's likely better regardless of the library.

cc @vladmoroz in case Base UI has specific views on this.

samuelsycamore commented 4 weeks ago

As I recall, the original motivation for introducing <ComponentCase /> was to help minimize the total number of words in any given doc that would need to wrapped in Backticks. Most of the time when we're talking about our components, we can just write "Button", "Switch", "Slider", etc. - plain proper nouns, no special formatting. This tends to look much cleaner overall.

Still, there are times when we need to refer specifically to the React component, and that's when we use <ComponentCase /> for clarity. There are two main use cases I've observed:

You could make a case for just using backticks in both of these scenarios, but then I think it becomes less obvious for the engineers writing the docs to recognize when to use plain text vs backticks. The impulse is to wrap all references to component names in backticks, which we want to avoid. Component case makes it as obvious as possible to both the writer and the reader that you're referring to the React component specifically. (Consider: If you read "Tab components" - does that refer to the suite of components needed to render tabs, or the <Tab /> components specifically?)

On a related note, I've also tried to standardize HTML tags as <html>, again, as a way to provide an immediate visual cue about what kind of code we're discussing.

samuelsycamore commented 4 weeks ago

I see that Base UI uses a mix of things e.g. https://base-ui.com/components/react-alert-dialog/

  • AlertDialog.Trigger
  • <AlertDialog.Trigger>
  • <AlertDialog.Trigger />

So I guess to standardize on a single approach? If one is better, it's likely better regardless of the library.

cc @vladmoroz in case Base UI has specific views on this.

I would love to see the styles in this doc standardized with the same rules we (try to) enforce on the rest of the product docs. To adhere to our rules, <AlertDialog.Trigger /> would be the correct format out of these three. I would also argue that there are many instances in this doc where you could simply write Trigger, Backdrop, Popup, etc. (no special formatting), unless there's a good reason for being as specific as possible on every mention.

vladmoroz commented 4 weeks ago

@samuelsycamore @oliviertassinari I am redesigning and rewriting all component docs as we speak, so feel free to ignore any emergent patterns in the current Base UI docs, I'll be going over that all anyway.

I agree with defaulting to proper nouns. At my previous gig, I went through tons content where every single thing that had a corresponding code concept was backticked, and it was impossible to make sense of a sentence like that. Glad we are on the same page here!

In the case of Base UI, most components are compound, so we'd use proper names to refer to components anyway. For example, casing and formatting in a sentence like this would make sense to me:

Not so sure about the parts and the exact convention to use to refer to React components when needed. A sane amount of formatting makes a document much more readable, and no formatting is similar to too much formatting in the sense that the document can become incomprehensible.

Check this out, a mock I created for comparison of the styles, using the upcoming design:

My personal preference would be (3)

(1) feels too dense; there's nothing for my eye to anchor on within the paragraph to scan it quickly. (2) is alright to me (3) feels spot on; instantly recognisable that it's in JSX land. The brackets are a way stronger indication than casing to me. (4) is better than (1), but my eye trips over the extra space in the self-closed comp and my brain instantly thinks that the text suggests that the nodes have no children (which isn't true).

Also, MDN consistently use <this> style, which many developers are trained to read. Self-closing comp feels especially unnatural when you need to reference a normal HTML element to me. See if you get a similar ick here:

Handy link to MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button

samuelsycamore commented 4 weeks ago

Cool, yeah it sounds like we're pretty much on the same page. (And I'm really glad to have someone else on the team to hash this out with in detail!) Ultimately I'd be happy with 3 or 4 out of the examples here, but if we go with 3 then we'll need to comb through the other product docs to apply it consistently without the self-closing slash.

FWIW, I got into the habit of <ComponentCase /> with self-closing since that's required in JSX land, and <html> with no self-closing since it's not strictly required. Your point about assuming that the nodes have no children when you see self-closing is interesting, though, and something I hadn't considered.

oliviertassinari commented 4 weeks ago

For the main topic of this issue https://www.notion.so/mui-org/Writing-style-guide-2a957a4168a54d47b14bae026d06a24b?pvs=4#128cbfe7b66080e4ad1fe0c0f359aa9e updated as it seems we will move forward with this.

@samuelsycamore thanks for the extra context. @vladmoroz the examples helps a lot, each image assessment feels accurate.

Overall, it seems that we could move forward like this? It seems pragmatic and easy to remember, how does it feel?:

  1. Most of the time when we're talking about our components, in general, we only write "Button", "Switch", "Slider", etc. - plain proper nouns, no special formatting. Why? Because this is much more readable.
  2. When using plain proper nouns, use sentence case when it's a reference to the general comment and Title Case when it's about our component. https://www.notion.so/mui-org/Style-conventions-for-MUI-components-and-products-dff7d2d7d1ba4a4abd47f48cf345b800
  3. Use backtick when you need to be clear which version of the component you're referring to. For example in the Tree View docs, "Tree View" is a reference to the general community component but "RichTreeViewPro" is a specific React exported module. It should be backtick. Why? Because this isn't clear otherwise. It's also hopeful not too frequent so won't harm the reading flow much.
  4. When we need to backtick:

Why? We format it like in the code. It's also not as heavy as < /> by default.

redesigning and rewriting all component docs as we speak

It would be great to have space for Sam to leave early reviews, syncing on the content style to minimize potential rework in the case where either Sam put light on a pattern opportunity improvements in Base UI or the other way around (a need to fix the MUI style guide).

vladmoroz commented 4 weeks ago

@oliviertassinari these rules sound good to me 👍

It would be great to have space for Sam to leave early reviews, syncing on the content style to minimize potential rework in the case where either Sam put light on a pattern gap in Base UI or the other way around (a need to update the MUI style guide).

Sure, agreed