Tooltips / glossary / help button for advanced concepts

[mvdbeek]

@jmchilton added some nice tooltips in #12912, and I think we should/could take this a bit further and describe a few basic unix concepts/terms in more detail (especially since they appear in the user interface and could be daunting to new users), like

• Exit Code
• Stdout
• Stderr
• Command line
• Traceback

Maybe this could be based on the how we do translations, and we could have a little help icon if help exists for these terms (I don't love tooltips, they can get in the way ...).

In the same way we should probably also provide a little help for Galaxy specific terms, like

• History ID
• History Content ID
• Dataset Collection / History Dataset Collection Association
• History Dataset Association
• Dataset
• Invocation
• Datatype
• Dbkey
• Job states

I think this could be a cool little collaborative project.

[assuntad23]

Functional Description:

Users can enable help mode on Galaxy to find and learn about features of the UI that are not very apparent at first glance. This help mode can be toggled on and off and will need to be manually added to any potential components that could benefit from the attention.  The component should be able to route to other parts of the Galaxy interface, link to GTN materials or other supplementary materials, pop-up additional context or help text for users, and know the job status of an item.  There will also exist a database table of all glossary items and only items that are “unlearned” will display. Users should be able to “learn” and thereby disable glossary items that are not relevant to them. 

Context:

• Newer users are overwhelmed by the interface
• Hard to find certain areas of interest or know how to use them without connecting them to tutorials or training materials
• Complex components that have a lot of power, but are only usable by folks who know how to utilize that power

Objective:

• Users can enable “Help Mode”
• Help Mode will highlight certain more confusing aspects of the UI and link users out to training materials or other supplementary materials

Goals:

• Highlight more complex abilities of UI 
• Easily link to tutorials, training materials, etc.
• Enable an easy way for future abilities to be modeled for users
• Help newer users learn about complex functionality
• Display/Model new capabilities to all users

Non-Goals:

• Cover every potential case where help mode would be helpful
• Implementing an AI model that would guide users through the process step-by-step

Proposed Solution:

Figma Design can be found here.

High Priority:

• Help Mode is enabled/disabled in the masthead and can be turned on or off at any point/from any location. This should be saved somewhere universal.
• Enabling help mode will add visible popovers with a “?” icon to any interactive items. This will be a standalone component, that will be added/visible only if help mode is enabled (AND the user has not dismissed/learned this item).
• When clicking the “?” icon/into the popover, the popover (or similar) will expand and display more information on context, links, etc. 
• All proposed glossary items will be collected/collated in a Google spreadsheet prior to being added. 

Medium Priority: 

• A user can dismiss a glossary item after viewing it. This will remove that popover from appearing on their account in the future (unless they re-enable it).  
• A list of enabled glossary items will be used to determine what should be visible before displaying them. 
• To implement this, a table will be added to the database for each user indexing the name (string) of each glossary item and whether it should be enabled or disabled (boolean). This will be used to create the table to determine what should be displayed.
• The glossary list is user-facing and can be found under User Preferences. They should be able to interact with it by:
  • Viewing what they have enabled and disabled
  • Enable/disable items from that view
  • This prevents users from dismissing a glossary item and then being unable to go back to it in the future.  

Low Priority:

• This glossary text will be stored in YAML file(s) instead of the database or in the component itself

Alternative Solutions:

• Help mode is stored in user settings, and user must navigate there to enable/disable
• Help mode uses color to signal that an item is interactive
• Help mode overrides tooltips/popovers that currently exist with additional interactive contexts

Timeline

Design Frontend: 1-2 Weeks
Get approval for design from GOATS & UI/UX: allow 2 weeks
Implement Database changes: 1-2 weeks
Implement Frontend (popovers and user preferences): 3-4 weeks
Implement Backend/Routing: 3-4 weeks
Enable Feature on History Components : 2-3 weeks
Enable Feature on Workflow Components: 2-3 weeks
Enable Feature on Tool Components: 2-3 weeks
Enable Feature on Miscellaneous Components: 2-3 weeks
Create Developer Tutorial on how to enable feature on new components/elements: 1-2 weeks

Expected Completion for: 23.2 release

[mvdbeek]

There will also exist a database table of all glossary items and only items that are “unlearned” will display. Users should be able to “learn” and thereby disable glossary items that are not relevant to them.

I personally think that might not be necessary for a first pass. My idea was that we should have a way to provide users with a way to learn what a History Dataset or an Invocation is with a ? icon that you can click on. And if the invocation help mentions History Datasets you should be able to click through to that glossary term. I was hoping for this to be integrated in the normal flow of the app, without a separate mode and state of what you have seen already (because you probably don't remember all of it the first time you read it).

[assuntad23]

There will also exist a database table of all glossary items and only items that are “unlearned” will display. Users should be able to “learn” and thereby disable glossary items that are not relevant to them.

I personally think that might not be necessary for a first pass. My idea was that we should have a way to provide users with a way to learn what a History Dataset or an Invocation is with a ? icon that you can click on. And if the invocation help mentions History Datasets you should be able to click through to that glossary term. I was hoping for this to be integrated in the normal flow of the app, without a separate mode and state of what you have seen already (because you probably don't remember all of it the first time you read it).

I agree that it doesn't have to happen in the first pass. That's why I put it as a Medium Priority. I think it'd be a nice to have. And it's worth noting that if I did enable that, I would make sure to also have a place for users to re-enable things they'd previously dismissed.

However, I do beleive we should add this as a seperate view. I think the toggle on/off is necessary. I only learned about this issue (#12934) yesterday, before that I was planning for what I believed an issue that did not yet exist - a help mode/interactive glossary view for Galaxy users (in particular newer users). It may be that the these are two different issues, as I'd like this to do more than just define terms. I'd like to see it point to Tutorials and other resources that could help a user find out what to do next. To do this well, I think a popover is necessary, as it permeates when you focus away from it, which makes it a better avenue for links, as opposed to tooltips.

Do you feel that is a different use case than what you initially were looking for when you created this ticket? If so, I could move this whole discussion to another issue, but @dannon thought that it had overlap here.

[assuntad23]

Out of UI/UX meeting:
I'm going to work on a Figma design for the side panel/help text that populates when you hover over an item that has help text. (Thanks @ElectronicBlueberry!)
And a glow/highlight design that glows when you hover over it, and then you can click it for the popover with help text. (Thanks @dannon!)
Then we can take a look at all three implementations alongside eachother and see if one stands out more than the others.

If anyone has any other ideas for UI implementation, let me know, so I can try to present that too.

[assuntad23]

Here's some Designs for the other two ideas:

Glow Design:

f

Panel (I put it in between the main screen and the History, but we could put it on the end too):

Both of these have seperate drawbacks.
The panel (as discussed in UI/UX meeting) would not operate well with our heavy use of modals. The not-so-simple answer here is to get rid of modals. But I'm open to other thoughts, too.
The highlight/glow implementation with popover (on click) would make it impossible to actually click the item. I suppose the answer for this one is to display the popover on hover instead, but then it will display automatically when mousing over any element that is in the glossary.

[tcollins2011]

Visually I prefer the Glow design more than the Panel design. It could also be possible to have the glow design popover on hover over the target element. I was also wondering if it would make sense to possibly implement this information as a tour as well so that a new user is guided to each of the elements rather than just naturally discovering them.

[assuntad23]

I was also wondering if it would make sense to possibly implement this information as a tour as well so that a new user is guided to each of the elements rather than just naturally discovering them.

I think adding a tour would be a nice follow-up, we can add that on later, for sure. Depending on how many different items/components we choose to highlight in this way, it might make sense to have multiple tours, broken down by "area".

[ksuderman]

One suggestion. As proposed, an item is considered learned when a user has viewed the item once and then dismissed the popup, but I frequently need to read something more than once before I have learned it. Could there be a "Don't show this again." checkbox (or similar) so an item is only considered learned when the user indicates they have learned it?

[hexylena]

Agreed with @ksuderman, having a way to revisit or re-activate old "learned" items is really useful for cognitive accessibility concerns (looking at you, every video game that doesn't let me revisit the interface tutorial when I've been away from it for a few months.)

[assuntad23]

^ yes, @ksuderman and @hexylena that was the idea that I was working towards. I also thought it might be useful to allow users to re-enable things that they'd previously dismissed in User Preferences.

I also tend to quickly click that "yes, I know this thing" only to realize that I need to see it again.

[assuntad23]

Adding some voting here:
🎉 for the "?" popover implementation
👀 for the glowing/highlight implementation
🚀 for the side panel implementation

if you already voted on the standup channel, no need to vote again here.

[ElectronicBlueberry]

In context of the UI/UX WG meeting: here's an example of how the info pane could alternatively be implemented:

(taken from ableton live)

[assuntad23]

@ElectronicBlueberry do you think a user would want to see this at the bottom of the tool panel or at the bottom of their history? That's why I added a whole new panel for it, because I couldn't decide which panel it should sit below.

[ElectronicBlueberry]

Tool Panel. The history requires more vertical screen space, due to the header, and height of the history items