edu
edu copied to clipboard
chainguard-dev
Surface glossary as shortcode blurbs
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 :)
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:
- Discoverability: Visitors probably won't know we do this.
- 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.)
- 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.
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.
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.
What do we think of this idea: we move everything in the glossary to the blurbs folder and I will write some template to autogen the glossary page by looking in the blurbs folder. That way as we write new blurbs they will automatically show up in the glossary page, and we'll have the option to embed any of these definitions as we write. Sometimes I want to have a details for things in the glossary like CVE and this would make these items accessible. Think this would be a relatively light lift, but we'd also want to encourage everyone to use blurbs more.
@smythp I would support that, maybe we mention it at the next team meeting to form a plan of action?