search

mdn / content

The content behind MDN Web Docs
https://developer.mozilla.org
Other
9.15k stars 22.47k forks source link

Issue with styles of glossary links #1735

Closed ghost closed 3 years ago

ghost commented 3 years ago

Page with the problem - a lot of pages, for example - https://developer.mozilla.org/en-US/docs/Learn

There are three glossary terms links on the page: HTML, CSS, JavaScript. At the start of 2020, links on glossary terms pages had dotted/dashed underline and had tooltips while hover with short definition from glossary page. Then it was broken (even before migration to Yari), at least at /Learn page, but worked in some other places. At this moment I don't see underline dotted/dashed links and tooltips at all.

Perhaps not an issue and you just removed this feature.

ghost commented 3 years ago

I don't understand. Can You please screenshot?

FTR https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn

ghost commented 3 years ago

Untitled

I'm talking about this. At the start of 2020 all glossary links on MDN were like this, with dotted underline and short tooltip generated from glossary page of that link while hover.

At this moment, they are just simple links, without dotted underline and short tooltip.

ghost commented 3 years ago

Ok. Time ago I proposed to fetch the meta description from link but this in another issue.

This Is the default dfn tag and if it Is used.

Anyway i think that all links should behave at the same way.

FTR https://developer.mozilla.org/en-US/docs/Glossary

Does the title of a match the <title> of the href document?

<a title=a href="./a">a</a>
ghost commented 3 years ago

It doesn't. If we are talking about glossary links, in title="" must contains the first paragraph or the first sentence from it's glossary term page. If I understood you correct.

For HTML term it's HTML (HyperText Markup Language) is a descriptive language that specifies webpage structure. For CSS term it's CSS (Cascading Style Sheets) is a declarative language that controls how webpages look in the browser. For Algorithm it's An algorithm is a self-contained series of instructions to perform a function. And so on.

At least this is how it was before, if I remember correctly.

ghost commented 3 years ago

https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title

The title global attribute contains text representing advisory information related to the element it belongs to.

Additional semantics are attached to the title attributes of the \<link>, \<abbr>, \<input>, and elements.

Is HTML an abbr? https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr

Glossary contains abbr and not abbr.

ghost commented 3 years ago

must contains the first paragraph or the first sentence from it's glossary term page.

document.querySelector("p").innerText;

document is not the current document but the linked one.

ghost commented 3 years ago

It's complicated because link should navigate on interaction and nothing else.

button should open things.

The tooltip is not shown on mobile. What Is the interaction on mobile?

ghost commented 3 years ago

Perhaps this is why the feature was removed (if it was removed) and all links now are the same.

I just remember there was such functional with tooltips and underline links on glossary terms. But can't find any information about it.

ghost commented 3 years ago

I like the functionality personally.

This Is Wikipedia

Screenshot_20210114-194046.png

ghost commented 3 years ago

I think wikipedia's solution is overkill for just glossary terms. Typical page on MDN (learning area) can have 4-5 glossary links. For me, personally, easier just open glossary link and read about it there, than scroll down-up or click [x] and then go back (and anyway open glossary link if I need more information).

This is why I liked solution with tooltips. You hover and get basic definition, and if you need more you just follow the link.

ghost commented 3 years ago

I think wikipedia's solution is overkill for just glossary terms. Typical page on MDN (learning area) can have 4-5 glossary links. For me, personally, easier just open glossary link and read about it there, than scroll down-up or click [x] and then go back (and anyway open glossary link if I need more information).

This is why I liked solution with tooltips. You hover and get basic definition, and if you need more you just follow the link.

I was thinking to a global tooltip component super accessibile done 1 time for all the needs 👨‍🔧🤷🏻‍♂️

Anyway id the page load fast Is not a problem to navigates for me. You can even share a page that Is good here in issues.

ghost commented 3 years ago

Founded old issue https://github.com/mdn/yari/issues/1452

Regarding old version personally I don't know how tooltip was implemented.

schalkneethling commented 3 years ago

Perhaps not an issue and you just removed this feature.

I assume those links contained one of two things:

  1. The word HTML was wrapped with an abbr with a title attribute or
  2. The anchor element had a title attribute with the text as you have demonstrated in https://github.com/mdn/yari/issues/2518#issuecomment-760290381

Perhaps as part of all the work that has taken place on https://github.com/mdn/content, this has been intentionally removed. @chrisdavidmills

Ryuno-Ki commented 3 years ago

From my experience, <abbr> are often styled by browsers with a dotted underline (and show a help cursor with question mark on hover).

That being said, title is generally not accessible on devices without hover (such as mobile).

peterbe commented 3 years ago

@chrisdavidmills I don't know if this is important enough worry about but it's a fair point that some links even go to the Glossary. For example, you might sit down to read about learning web dev, and then you follow the link and you're now on a Glossary page. As per the screenshot there, the CSS link should either go to /en-us/docs/web/css or not be a link and instead be something like:

...
learn <abbr title="Definitiona of the word HHTML here">HTML</abbr> and <abbr title="Definition of the word CSS here">CSS</a> in detail:

MDN came from being a Wiki which originates a certain style, where every word that can be a link becomes a link. But I think it's a poor thing to have in a section like the "Learn" page which is meant to navigate you in the right (deeper) direction.

chrisdavidmills commented 3 years ago

I don't really have time to think about this right now, but ... we ended up removing title tooltips in places where they were used (like xrefs and glossary entries) because of their inherent accessibility issues. At this point, the glossary links just link through to the glossary pages, which is OK — you still get the definition.

I think all I'd do here is to perhaps remove the glossary links from this page. There are already other links that take the reader down the right path to learning these technologies.

Or maybe even do nothing — the definitions ares still helpful...?

peterbe commented 3 years ago

Tooltips or not, I think the links are distracting. We're not a wiki anymore. We need to avoid peppering the pages with too many links because a little portion of your brain is losing concentration when you have to make microdecision ("Do I have to click to read more about at what CSS means?? I can't decide. Maybe. I'll just open it in a new tab for now"). I think the prose would read better if it was something like this:

<p>If you have a bit of knowledge already, the next step is to learn HTML and CSS in detail: start 
with our Introduction to HTML module and move on to our <a href="/Learn/CSS/FIrst_step">CSS 
first steps module</a>. (To read more about what CSS means see the <a href="/Glossary/css">glossary 
page for CSS</a>.</p>

@chrisdavidmills No action required. Just various interesting thoughts and opinions here about deep linking and style.

chrisdavidmills commented 3 years ago

Agreed. OK, so I think we should get rid of the three glossary links.

peterbe commented 3 years ago

Yari lost the functionality of formatting links to the Glossary pages. Sorry, didn't notice that. But @Ryuno-Ki makes a good point about the in-accessibility of relying on tooltips. Plus the problem with mobile devices. And I made the argument that just because have a Glossary page about some term, there are a whole of times where a link to it might just be distracting from a "learning perspective". Points to which @chrisdavidmills agreed. So can we close this now? How do you feel about that summary @Torhuo ?

Ryuno-Ki commented 3 years ago

But @Ryuno-Ki makes a good point about the in-accessibility of relying on tooltips. Plus the problem with mobile devices

Today I filled https://github.com/mdn/yari/issues/2705 regarding tooltips.

ghost commented 3 years ago

@peterbe Well, the main reason for creating this issue was to understand is a missing underline and a tooltip bug or not. Looks like not a bug, so the main problem solved.

About changing glossary links. I like this decision.

I think the prose would read better if it was something like this:

<p>If you have a bit of knowledge already, the next step is to learn HTML and CSS in detail: start 
with our Introduction to HTML module and move on to our <a href="/Learn/CSS/FIrst_step">CSS 
first steps module</a>. (To read more about what CSS means see the <a href="/Glossary/css">glossary 
page for CSS</a>.</p>

But the main page of the learning area was just an example. What about other HTML, CSS, JavaScript glossary links on other pages?

For example:

And so on. I just want to know what to do in such cases. Remove unnecessary glossary links, change text like you (for me unavailable, because of my poor knowledge of English language) or do nothing?

Because at this moment, there are A LOT of unnecessary glossary links, in my opinion. I can understand glossary links for rare terms or things that not explain in the article. But why, for example, in the article ( https://developer.mozilla.org/en-US/docs/Learn/HTML/Introduction_to_HTML/The_head_metadata_in_HTML ) about <head>, exist glossary links for metadata, head if it explains inside this article below? Or glossary links for elements and tags in the article about structure of HTML elements. I think such glossary links should be removed.

peterbe commented 3 years ago

It's hard to get everything right but we can set our minds on the same track. Sometimes, in certain documents, it's very appropriate to have a link to the glossary. I'm too lazy to find a good example but there could very well be pages where a much more complicated term is mentioned but one that we don't have a page for. For example, image some page that talks about using background images in CSS and it might mention "PNG" and there it would be appropriate to link to the glossary page for PNG.

Let's not mass-fix anything now. But we've all learned some interesting stuff about glossary links, reading-flow, accessibility concerns, etc.

Close?

ghost commented 3 years ago

Yes, I think we can close this issue now.