Add hover-over/pop-hover functionality to Docs, for Glossary entries

[ninavizz]

Checklist

• [x] This issue follows the Issue Tracking Guidelines.
• [x] I have searched both open and closed issues for duplicates.

---

The problem you're addressing (if any)

Qubes is hard. While Qubes began as an academic project, most many end users are not academics—and we are not aspiring to support academics or people with strong backgrounds in academia, as our primary user base. As such, more needs to be done within our documentation to support users with a lower attention span, and without established habits of quickly learning new information with a steep learning curve.

For this specific issue, the pain-point within the above is that Qubes OS introduces many new terms-of-art specific to either Qubes, to hypervisor-things, or to infosec. As an example: it is important to understand what a hypervisor is, if you are reading a paragraph of information about it. That compounds, when a paragraph uses multiple words that a user has never before seen or experienced. Academics have the built-in rigor to look everything up as they need to; however, it is preferable to alleviate that, if easy technical mechanisms might exist to quickly/simply provide a glossary explainer for them, in context.

Describe the one solution you'd like

It was suggested in #6756 that a terrific way to enhance the learning experience of folks navigating the documentation, would be to extend the front-end of the docs to support the feature described in the subject of this issue. I 100% agree, and also feel it could lower the burden of community management and Forums questions, if we make the effort to make the docs a richer and more intuitive learning experience for people.

I'm sure that plugins or other quick features exist as a part of Jeckyl, Bootstrap, or other libraries, to simply/easily do this. I would love to consider whatever those options might be, as I don't feel this need merits a bunch of custom work—and that anything, is better than today's nothingsauce.

Where is the value to a user, and who might that user be?

1. Docs users. Any user without a PhD, or any human not desiring the burdensome process of looking-up everything they do not immediately understand. Fun fact: very few users bother to look-up things they don't understand. Even when it would suit them to do as much. 2. Forum users. Redundant content makes for un-interesting user communities. Seeing the same things asked over and over again, or conversations that emerge from mis-understanding, reduces community engagement. 3. Community moderators. Maintaining a text file of cut-and-paste friendly sentences to direct people to Glossary entries, is an easy thing to avoid when you meet users where they're at and make these definitions easier to discover in-context.

Describe any alternative solutions you've considered

Andrew could write an entire novel within this section, of his many polite and empathetic workarounds to screaming RTFM to folks. :)

Additional context

Learning is good!

---

Relevant documentation you've consulted

Ok. At this point in the issues template, I'm mentally exhausted and just want to submit the new issue, before my browser crashes.

Related, non-duplicate issues

found. None

[andrewdavidwong]

Quoting myself from https://github.com/QubesOS/qubes-issues/issues/6756#issuecomment-873385039 to provide some additional context and information:

We could easily split up each glossary entry into a separate Markdown file (in _includes/?), but it's unclear how best to code the site in a way that will allow those definitions to be accessed organically in other text, especially in a way that also works on mobile devices with no cursor to hover.

---

Nina wrote:

I'm sure that plugins or other quick features exist as a part of Jeckyl, Bootstrap, or other libraries, to simply/easily do this.

I would love that, but unfortunately my searching hasn't turned up any easy solutions. Bear in mind that we can use only the Jekyll plugins supported by GitHub Pages. Most of the solutions I'm seeing would rely on jQuery and probably require custom coding for our website. :frowning_face:

[ninavizz]

Thank you for nosing around a bit on this, @andrewdavidwong. That's a big bummer.

Yeah, come to think, given the security needs of many of our users and the possibility that folks will be on Tor and w/o Javascript, this could be a toughie. @antoneladebiasi may have some ideas, from having worked on stuff for Tor. I'll ping her outside of GH.

[ninavizz]

Well, shoot. Tor's documentation doesn't do this, either.

[DemiMarie]

Yeah, come to think, given the security needs of many of our users and the possibility that folks will be on Tor and w/o Javascript, this could be a toughie. @antoneladebiasi may have some ideas, from having worked on stuff for Tor. I'll ping her outside of GH.

This is a strong argument to provide a qubes-docs package, which provides the documentation from a file:// URL.

[andrewdavidwong]

This is a strong argument to provide a qubes-docs package, which provides the documentation from a file:// URL.

We already provide the repo with readable plain text documents and the ability to serve the site locally.

We're also working on offline documentation (#1019).

But most users will not use any of these alternatives over the online website unless we make it super easy and frictionless for them.

[GWeck]

I hesitate to point towards a government website, but the German BSI does quite a good job in explaining terms in their texts. The term is just underlined, and if you hover the mouse over it, an explanation pops up. This is done just with standard HTML, using constructs like

<abbr lang="en-GB" title="Transmission Control Protocol/Internet Protocol" xml:lang="en-GB">TCP/IP</abbr>.

For an example, see Recommendations for critical information infrastructure protection.

Perhaps such a help funktion could be integrated without too much effort into the (currently already exceedingly good!) documentation.

[andrewdavidwong]

I hesitate to point towards a government website, but the German BSI does quite a good job in explaining terms in their texts. The term is just underlined, and if you hover the mouse over it, an explanation pops up. This is done just with standard HTML, using constructs like

<abbr lang="en-GB" title="Transmission Control Protocol/Internet Protocol" xml:lang="en-GB">TCP/IP</abbr>.

For an example, see Recommendations for critical information infrastructure protection.

Perhaps such a help funktion could be integrated without too much effort into the (currently already exceedingly good!) documentation.

Thanks, @GWeck! This is a good solution for desktop browsers, but unfortunately it doesn't work on mobile. Nonetheless, perhaps it's good enough to implement. Better to improve the experience for some users even if we can't improve it for all of them.

Some kind of JS solution would likely be required to make abbr work on mobile, which could be pursued later.

Now, the question is how best to handle this in our Markdown docs, since we want to avoid HTML there.

[andrewdavidwong]

Now, the question is how best to handle this in our Markdown docs, since we want to avoid HTML there.

Not only do we want to avoid HTML, but we definitely don't want to duplicate the source text of each glossary entry across multiple pages. It seems like we'd have to do something like this:

Create _data/glossary.yml containing a list of entries like this:

- term: "admin qube"
  def: "A type of qube used for administering Qubes OS."
- term: "app qube"
  def: "Any qube that does not have a root filesystem of its own. Every
       app qube is based on a template from which it borrows the root
       filesystem."
[...and so on for the rest of the glossary entries...]

Add the following to _includes/variables.html:

<!-- Glossary -->
{% assign glossary = site.data.glossary %}

Create _includes/glossary.html that looks something like this:

{% include variables.html %}
{% assign glossary-entry = glossary | where_exp: "entry", "entry.def == {{ target_entry }}" %}
<abbr lang="{{ lang }}" title="{{ glossary-entry.def }}" xml:lang="{{ lang }}">{{ glossary-entry.term }}</abbr>

Finally, in the text, write something like:

Qubes OS is an operating system built out of securely-isolated compartments
called {% include glossary.html | "qube" %}. For example, you might have a work qube, a
personal qube...

Several problems:

• _includes/glossary.html is probably wrong, and I'm not sure how to handle {{ target_entry }}.
• I don't know whether something like {% include glossary.html | "qube" %} is actually possible.
• This will result in "compartments called qube" rather than "compartments called qubes." In other words, this method gives us no good control over pluralization. Appending an "s" outside of the liquid would result in only the first four letters being underlined, which would look bad. Some terms can't be pluralized that way. Would most likely require some custom coding to handle pluralization.
• This prevents us from having long glossary entries with rich formatting and hyperlinks in the definitions like we currently have (example).
• This makes the source doc files pretty tough to read compared to regular Markdown.

[marmarek]

Having a custom jekyll plugin could make it work (if one knows how to write it...), but I think we cannot use custom plugins if the website is generated on github pages. We'd need to generate it ourselves (in gitlab-ci maybe?) and upload for hosting as resulting HTML files. This is BTW how gitlab pages work already, which gives much more flexibility.

[ninavizz]

This example from a Docs theme in Jekyll is reasonably ok, but would be difficult for how our glossary is currently done—with the one-sentence "definition," followed by clarifying bullets (which Qubes needs). I don't know how it may or may not interfere with the usual alt-tag text required for screen reader.

In an ideal universe, the popover would show the first sentence of all definitions, then have a "Read More" kind of a link to see the full entry. Or, it would show the portion of a definition contained in a tag to show-up in the popover, with the "Read More" link. Fortunately the Qubes glossary is not so extensive, that doing that work would be too hard; building said plugin would likely be harder.

The Jekyll website also appears to have a good guide on it for making plugins, and it all seems to be orchestrated to work with GitHub pages.

@GWeck Government websites from countries/States with good digital service delivery teams, are actually some of the best in the world! I realize they all have a ways to go with getting their act together on the digisec front, but from a UX and accessibility perspective the UK, and Germany are longtime leaders in best frontend practices. Not digisec, frontend & UX. :)