Provide terminology definitions in tooltips

Similar to the tooltips for footnotes feature requested in Make footnotes appear in a popover (#396 - closed), could we also support tooltips for terminology definitions? This would allow us to reduce excessive linking across the site for simple definitions that could be provided inline. This avoids sending the user away and disrupting their user journey.

Implementation plan

  1. MVC: Experiment with using the <abbr> HTML tag (see discussion below). Ensure this is an accessible option that also works in /help and document its usage in the style guide.
  2. Future potential enhancements (let's create new issues for these if we decide to pursue them):
    • Improve visual styling of the tooltip
    • Support markdown in the tooltip (links especially would probably be nice)
    • Glossary/shortcode approach (see this comment)

Context

@rdickenson: The Sec section has a lot of terms that are both generally well-known in the industry but whose precise meanings are sometimes debated. Phillip and I propose linking the first instance of specific terms on a page to the Security glossary [1]. I know we’re working to minimize links but it’s important that users can quickly reference and understand these terms. Objections? How are we doing this in other areas of the product? For example, subscriptions has a lot of GitLab-specific terms, similarly for our planning features.

Ryan: Maybe a tooltip would be a suitable UI component to consider here? That way it doesn't break the user flow in the same way (the user doesn't actually leave the page). Looks like there is already some limited support for tooltips in the Hugo site.

Styling

Ideally, the styling for the tooltips would be visible and different from link formatting, but not overly intrusive.

Automation vs Shortcode approach

Two approaches have been discussed:

  • Automation: For each "term" we want to support, automatically add the tooltip automatically to the first instance on every page the term is used.
    • No additional work for contributors.
    • Adds potential for confusion--say a term like "analyzer" or "container" that has a specific meaning in the security docs, but could easily be used in a generic sense elsewhere.
    • I'm not sure what the answer to this would be: @platteier : To automate tooltips, we'd need some way to identify which words need tooltips and what the tooltip should say. For the footnotes, I rely on the tag and the footnote list after the table
  • Shortcodes: Manually (or via script) apply a shortcode that replaces the first instance of a supported "term" to the first instance on every page it's used.
    • Requires manual work to add it.
    • Give us full control over usage.
    • Maintenance could be done via a new monthly maintenance task, but not strictly necessary. If done, we may need to support exceptions where we don't want the tooltip, so it shouldn't be flagged every time.
Edited by Sarah German