-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
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.
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
[docs] Improve the getRowId
doc section
#5156
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
41112d9
[docs] Improve the getRowId doc section
flaviendelangle 5ae1e92
Update docs/data/data-grid/rows/rows.md
flaviendelangle 7927aae
Update docs/data/data-grid/rows/rows.md
flaviendelangle 3b71e9c
Update docs/data/data-grid/rows/rows.md
flaviendelangle a510f8d
Prettier
flaviendelangle File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are we sure about the number of line breaks? It feels challenging to skim read, there are multiple paragraphs that feel talk about almost the same topic:
I would personally enjoy reading this denser version (1. what it is, 2. behavior/configuration 3. a demo):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We can improve that one in #5195
I felt like it was already an improvement and could be shiped as is if needed
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@flaviendelangle For sure 👍 . This is only an instance of a larger topic.
My root question is about: what should be our general practice about paragraphs and what's our threshold to split sentences into multiple paragraphs once the content cover is too further away? It's mostly a question for @samuelsycamore. We started to surface the matter in the past. I feel that our current threshold is too low, I want to advocate for the side that says: we don't group enough. Another instance was mui/material-ui#32325 (comment).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Both of these look good to me, so I'm happy to accommodate either style. I would say that in general, I don't think paragraphs should be any longer than they are in the latter version. With dense material like this, it's easy to get lost in the middle of a paragraph.
I think this paragraph is the ideal length for text like this:
So we could say that as a general rule, you should consider a line break after 2 sentences or ~200 characters.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cc @mbrookes for perspective on the matter.
If we were to look for rules that could work in practice, I would personally imagine that above 500 characters, a paragraph is either too verbose to cover one matter and should be broken down, or it's actually covering multiple matters and hence should be broken down too. In the docs of Stripe (one I would assume receives a lot of care), it's common to find paragraphs of almost 400 characters e.g. https://stripe.com/docs/products-prices/how-products-and-prices-work but It's hard to find one above 500.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm with @oliviertassinari on this one. The second example is superior to the first. But if they needed to be to convey the concept, each paragraph could comfortably be twice as long. I don't think that there should be an arbitrary rule on paragraph length – paragraphs aren't measured in words or sentences; but I agree that verbosity should be eliminated, and that paragraphs should cover one narrow topic.