search

chainguard-dev / edu

Educational Resources for Software Supply Chain Security
https://edu.chainguard.dev
Other
73 stars 55 forks source link

Add tooltips for vocabulary words #893

Open mcaveety opened 11 months ago

mcaveety commented 11 months ago

Is your feature request related to a problem? Please describe. The glossary is helpful, but you have to hunt it down in the hopes of finding a term.

Describe the solution you'd like Having vocabulary words in the glossary get ingested and used to create tooltips on hover-over of words would be a great way to utilize and link back to the glossary more often! Also makes the website a bit more interactive / tactile

Describe alternatives you've considered Right now, we do occasionally link words directly to the glossary but the lack of hover-over tooltip does make it a bit cumbersome to navigate back and forth between pages. We also embed definitions within our articles, which is good when introducing concepts in their focused articles, but not the best in cases where we want to focus on a different topic and assume certain things as knowledge.

Additional context I could draw something to represent this :)

mcaveety commented 11 months ago

@ltagliaferri how does this look? I put it as status - backlog for now.

smythp commented 1 day ago

I think that maybe we should more aggressively create shortcode blurbs summarizing specific topics. I've been doing this recently with, for example, deep learning and CVSS. The issue I have with hover-and-show are the following:

  1. Discoverability: Visitors probably won't know we do this.
  2. Least surprise. You don't necessarily expect things to pop up when you hover and you might be trying to do something else, like copy. (I copy a lot and kind of hate popups that want me to share on Twitter or whatever.)
  3. Accessibility. Hover and show would only be accessible to mouse users, and for keyboard/screen reader users it would be too verbose.

That said, I do think we use terms like CVE and various othersecurity-related items without referring visitors to definitions, and that some articles that are more introductory should do this more. If we wanted to pursue this, maybe we could add more definitions from the glossary to our blurbs folder and then use them more prolifically as a house style.

Wondering what @sheesh and @SharpRake think.

SharpRake commented 18 hours ago

I agree with @smythp's points. While tooltips can be cooltips they aren't always intuitive and in something like docs I think an easier solution is to modularize heavily reused content like definitions with blurbs.

mcaveety commented 3 hours ago

This makes sense, thanks guys! Me & Lisa had discussed this about a year ago but I don't recall it ever being discussed with the whole team. I agree, adding more blurbs and expanding the glossary may be a better way to address this going forward. The implications for accessibility are also super important, so thanks for raising that.