[docs] Improve fragment links #18667
Conversation
eps1lon
added
new feature
Details of bundle changes.Comparing: b14c7a4...f27b8fe
|
|
When I want to link to a specific prop.
https://css-tricks.com/ does it. But more importantly I can link you many documentations that do it badly: everyone that reveals the links on hover while focus does not reveal them. Reveal on focus is an option but it's simpler to always display them anyway so that we don't have to rely on knowledge of convention. |
Interesting, I'm wondering because I tend not to take the time to provide an exact link to the API page, I tend to mention the name of the prop, and move to something else. I'm curious to see how people will use this link.
I believe that most remove the anchor from the tab sequence. Is that an acceptable approach? If we do display the anchor, what about reducing its size to minimize the impact on readability? Or maybe reduce its contrast? @mbrookes What do you think? |
That would be worse. Links should be in tab sequence since that is their default behavior. |
Again that is worse. I'm not sure why reducing readability is a target for you. The default target is better readability. You would need to explain how reduced contrast or size improves readability or rather that the content is better perceivable. |
|
My assumption is that for 100 given page displays, 1 will be about clicking on a header link to later share it. I suspect that displaying the anchor reduces readability as somebody would have to process what's this unexpected (as not frequently seen) element is about. It's only later, once he wires a model in his head to automatically ignore the display of the element that the negative impact on readability gets sorted out. This makes me think of the "Law of Past Experience" in the Gestalt theory, and how this rule take precedence over the other ones. I don't know how reproducible this school of psychology is, but from the examples provided online, I have seen these rules work on myself. I believe that past learning people have built is very hard to break. It's one of the reasons why I love benchmark. Sometime, it's best to go with what the majority does, but not always as the majority !== what is right. |
|
Regarding how GitHub handles markdown's headers, do you think that they should change it? |
I can't help thinking we've been around this loop before. I recall that when iterating on the TOC, at one point we were setting the hash fragment automatically, as material.io does, but that this was subsequently removed. I can't remember the specific context, but I do know we experimented with displaying the hash symbol by default, and ultimately changed it for the same reason you have given here. I don't think discoverability of this feature is an issue. The small minority that want to link to a subsection already know how to find it. (Personally, I go as far as finding the id in the source if the site doesn't provide the feature we currently offer). I had missed the change of icon from the hash to the link icon. No strong preference, but I have a niggling feeling the link icon has a different meaning in other contexts.
Sorry to say, but this just adds noise. What are these links? Where do they link to? Why does nothing much appear to happen when I click on them (other than the page moving a bit)? |
@mbrookes I did this change recently, to better match the experience on React and GitHub. I have tried to move the anchor from the right to the left too but without much success.
|
I don't understand the question. Unless I interpret this as you asking what a link is this statement is pure provocation. Since I've been asked to reconsider my communication I'd like to extends this to you as well. I already added one use case (personal communication) and want to add another one: Referencing prop descriptions on other pages to de-duplicate the description. This will be used for the label vs. labelWidth description in #17680
They link to prop which is part of the link name.
This is the basic behavior of the platform. Please take a step back and re-examine how you can justify going to the page source to find an id as a good signifier but reject fragment link affordance which is a basic feature of the web since it's inception. Why does this argument not apply to the current fragment links? They don't do much either and don't even have a name.
I agree since I had trouble finding a proper name for that icon. I don't think it's part of the Material icons anyway (the "link" icon looks different). I'd prefer the hash since we then have a 1:1 mapping to link hashs and document fragments.
I extend a little bit more intelligence to our readers. I think they are capable of processing an icon while reading. This argument is again backwards ("I need to support my feelings so I construct an objective argument"). Why does this not apply to emojis? If this is a concern I'd rather move it to the start and out of the text alignment. Heading and paragraph have the same left alignment but the fragment link is clearly outside of the document flow.
I repeat what I said before: yes.
This reveals the fundamental issue with your thought: The majority usage makes no statement what so ever about if it is right. It just means that it is used by many. Nothing more. It may be correlated but not caused. Convention can only be considered a sginifier if it is indeed convention. It is not though. Cherry-picking your side does nothing to advance the discussion. It only tries to win an argument which I don't care about. |
- alt in a image within a link should describe the link - added title to explain purpose for visual browsers
This is very possible, I think that humans are post rationalizer creatures, we are very rarely rationale, maybe 10% of the time. I think that the topic we are discussing is mainly on the human psychology level, we are looking for levers to provide the best-perceived experience. In this context, I think that providing the experience readers have learned, in the past, on the others documentations can be very effective. I would recommend going with that: look at what models developers have learned, and provide the same experience. Now, I might not be always ideal, nor right, considering somebody that is willing to invest the cognitive effort to learn a new experience. If you think that an always visible anchor link is better, I think that we should move it to the left side before deploying the change. So people can start reading just after it.
Thanks for the confirmation, the position is very clear. |
So, should we go with a # icon instead? |
Then perhaps I should have put them in italicised quotes. This was the imaginary internal dialog of someone using the prop docs, outside the context of this PR. I thought it would be apparent that these were not actual questions. My bad.
I'm not at all opposed to the props having fragment identifiers, but I personally think it would both offer a better affordance, and be less visually intrusive, to use the same approach we currently use for the page headings.
I'm not rejecting fragment links, I'm asking whether the proposed method for setting them is the best option.
Because the icon indicates that the purpose of the link is to set the fragment id, this being a pattern that is used widely enough to be recognisable to the majority of users.
Thanks for the background. |
I could narrow it down to vercel/next.js#6904, or at least, it's present on a blank page with Next 8.1.0 and solved with 9.1.4. Hopefully, it will be solved with #18441 :). |
|
What do you think of this tradeoff: https://www.telerik.com/kendo-angular-ui/components/inputs/slider/? There is no anchor/link icon, but the headers are links, this looks like an interesting compromise. |
|
@eps1lon What do you think of scoping the changes to the hydration issue (point number 2) in this pull request? I think that the link changes will need further iteration. |
|
See internal chat. |
Example: https://deploy-preview-18667--material-ui.netlify.com/api/app-bar/
Affordance was only discoverable with hover (suboptimal). It's now obvious as well as accessible to everyone.
Use
<symbol />to ship (large) path once and reference it multiple times while being able to use:hoverstyles (which is not available in<img src="*.svg" />. Deduplicates labelling as well.titlefor fragment links to explain explicitly where the link goes