Contextual help (e.g., explanatory tooltips) for Qubes UI elements

[andrewdavidwong]

Consider support for explanatory tooltips whenever hovering the cursor over a Qubes UI element. For example (based on #1855 (comment)), when hovering over the "Pause" button in Qubes Manager, the tooltip currently just says:

Pause selected VM

Instead, it could say something like:

Pause selected VM

Stops all CPU activity in the selected VM until the VM is unpaused. This action does not change how much memory is allocated to the VM.

[andrewdavidwong]

To clarify, this should be fully compatible with decomposition of the existing Qubes Manager (#2132). Presumably, there will still be Qubes-specific GUI buttons of some kind somewhere. Even if there is no longer a "Pause" button, there will probably be other UI elements that would benefit from an explanatory tooltip.

[andrewdavidwong]

On 2016-08-13 09:35, amadaus@[...].net wrote:

I do not recall being prompted to create a USB VM during installation of 3.2
rc2. However, I've now successfully created one and it works fine. But I'm
jittery that my system's integrity has been comprised by a compromised USB Flash
stick.
I guess the only solution is to ditch my current VM's [including backups] and
reinstall qubes?
It would be really good if the developers could modify their code to prevent
users from accidentally falling into this unfortunate trap.

IMO, this would be a prime candidate for an explanatory tooltip in the installer. When the user hovers over the option to create a USB qube during installation, explain (among other things) that creating the USB qube will be problematic if the user's only available keyboard is a USB keyboard, while not creating a USB qube will leave dom0 exposed to malicious USB devices.

[andrewdavidwong]

Perhaps another good candidate for an explanatory tooltip:

On 2016-08-12 15:31, johnyjukya@[...].org wrote:

(Also, Temporary OS updates are indeed handy in the AppVM's for testing or
one-off app runs, but leaving this checkbox on is just like turning
networking full-on for the AppVM. The user should at least be aware of
this fact. I wasn't.)

At the very least, the GUI should educate the user about this fact, and
maybe pop up a warning/confirmation page if the user tries to enable update
access for an AppVM.

[andrewdavidwong]

On 2017-03-04 06:35, sm8ax1 wrote:

The first-boot options dialog could have explained the options a little
better, or they should be explained in the documentation. For example,
the option to proxy all applications and upgrades through Tor, I
selected it because it sounded like what I wanted, but I didn't really
understand how it would affect the networking VM hierarchy or whether I
could still create unproxied VMs. I left the USB VM (sys-usb) option
unselected because I wasn't sure how reliable it would be, I don't have
an IOMMU anyway, and I don't connect a lot of random USB devices to my
computer, but I would like to try the feature in the future. All along I
was thinking "Can I change my mind later? Am I stuck with these
decisions for the rest of my life?"

[kalkin]

Do we still need tooltips in the Domain Tray? Currently the sub-menus are self explanatory, aren't they?

[ninavizz]

"Tooltip" can mean a lot of things—and is often confused for "Alt Text." For the reasons cited in #6669, alt-text needs to be reserved to serve accessibility needs–whereas a different visual treatment, needs to be developed to explain functionality to users in-situ. That pattern is known among UX folks, as "Contextual Help."

[ninavizz]

@andrewdavidwong @marmarta Is a lot of new tooltip-ing being deployed in 4.1, for which this would need that milestone—or can we change this Issue's milestone to "ongoing," as (to me, at least) this feels like an ongoing clean-up task?

[andrewdavidwong]

"Tooltip" can mean a lot of things—and is often confused for "Alt Text." For the reasons cited in #6669, alt-text needs to be reserved to serve accessibility needs–whereas a different visual treatment, needs to be developed to explain functionality to users in-situ. That pattern is known among UX folks, as "Contextual Help."

According to https://en.m.wikipedia.org/wiki/Tooltip, it sounds like "tooltip" is the standard term for what this issue was originally about, whereas https://en.m.wikipedia.org/wiki/Mouseover is the more general thing that also includes alt text.

Thanks for introducing me to the concept of https://en.m.wikipedia.org/wiki/Context-sensitive_help. It appears to be newer and... patented by Microsoft?!

But I agree with the general principle that it doesn't have to be a mouseover or a tooltip. For example, the help text could be displayed without any hovering in some cases, or may be something other than text. Whatever works best.

Is a lot of new tooltip-ing being deployed in 4.1, for which this would need that milestone—or can we change this Issue's milestone to "ongoing," as (to me, at least) this feels like an ongoing clean-up task?

My concern about "ongoing" is that the issue will never get closed and sprawl forever. This is intended to be more like, "We have no tooltips. Let's implement a baseline set of tooltips for our existing features, then close this issue." Subsequently, part of implementing any new feature should include adding appropriate tooltips for its elements.

[ninavizz]

"Tooltip" is one of those oddball terms, that folks sometimes conflate with alt-text tags—simply because the alt-text functionality is built into browsers, whereas correct/actual "Tooltips" one must build separate from native browser capabilities. The richer functionality #6669 seeks to standardize as a pattern is both accessibility-friendly and more visibly discoverable, for tooltips. :)

Folks with screen readers depend upon alt-text tags for text elements only echoing what the text elements "say," as alt-text tags are what screen reader software reads-aloud to guide vision impaired users to navigate pages that sighted users are able to visibly read. If that makes sense. Tooltips are a secondary "FYI" kind of information piece, so need to not replace the purpose that alt-text tags have with supporting visually impaired users.

PatternFly is an open source interaction patterns library managed by RedHat, that I've become incredibly fond of. There is a tab on the aforelinked page, marked "Design Guidelines" that offers terrific guidance on when to use which kind of tooltip, and how to best compose the content of tooltips. I highly recommend it for all Qubes contributors! The standard that I proposed in #6669 is for what Patternfly has marked "Icon Tooltip." In tables and other views, including an icon is not possible—or would create a far too busy layout. In those contexts, the simpler text-based tooltips are advised.

@andrewdavidwong Would it help to identify which components still need tooltips, as acceptance criteria for eventually closing this issue?

[andrewdavidwong]

Would it help to identify which components still need tooltips, as acceptance criteria for eventually closing this issue?

Yes.

[andrewdavidwong]

Another place explanatory tooltips are needed is the Qube Manager's table headings:

https://forum.qubes-os.org/t/basic-knowledge-about-qubes-manager/9878/

[andrewdavidwong]

It would be helpful to have tooltips in the Qube Manager when hovering over the various different qube icons to explain what they mean. Right now, one has to read through the whole discussion on #5676 to understand some of them.