Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
oliviertassinari opened this issue Oct 22, 2024 · 8 comments
Open

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

oliviertassinari opened this issue Oct 22, 2024 · 8 comments
Labels
docs Improvements or additions to the documentation scope: docs-infra Specific to the docs-infra product

Comments

@oliviertassinari
Copy link
Member

oliviertassinari commented Oct 22, 2024 •
edited by github-actions bot
Loading

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:
@oliviertassinari oliviertassinari added docs Improvements or additions to the documentation status: waiting for maintainer These issues haven't been looked at yet by a maintainer scope: docs-infra Specific to the docs-infra product labels Oct 22, 2024
@oliviertassinari oliviertassinari mentioned this issue Oct 22, 2024
Merged
@oliviertassinari oliviertassinari removed the status: waiting for maintainer These issues haven't been looked at yet by a maintainer label Oct 22, 2024
@samuelsycamore
Copy link

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
Copy link
Member Author

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/

  • 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.

@samuelsycamore
Copy link

samuelsycamore commented Oct 23, 2024 •
edited
Loading

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:

  • When you're referring to multiple components that have similar names, for example, the Base UI Tabs doc: "Tab components" generally, <Tab />, <Tabs />, etc. specifically
  • When you need to be specific about which version of the component you're referring to, for example the Tree View docs: "Tree View" generally, <RichTreeViewPro /> specifically

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
Copy link

samuelsycamore commented Oct 23, 2024 •
edited
Loading

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
Copy link

vladmoroz commented Oct 23, 2024 •
edited
Loading

@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:

  • ”Use Popover instead of Tooltip for popups that contain interactive elements”

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:

  • This part renders a button tag
  • This part renders a <button> tag
  • This part renders a <button /> tag

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

@samuelsycamore
Copy link

samuelsycamore commented Oct 23, 2024 •
edited
Loading

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
Copy link
Member Author

oliviertassinari commented Oct 23, 2024 •
edited
Loading

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:
  • <Menu.Root> when requiring a child, most components
  • <RichTreeViewPro /> when it's a self-closing component

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).

@oliviertassinari oliviertassinari transferred this issue from mui/material-ui Oct 23, 2024
@vladmoroz
Copy link

@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

This was referenced Oct 23, 2024
Merged
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Improvements or additions to the documentation scope: docs-infra Specific to the docs-infra product
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@oliviertassinari @vladmoroz @samuelsycamore