Contextual Help

[heathergreerklein]

From release plan spreadsheet

Estimate from release plan: 32 hours
Expressing interest: 4Science

No additional notes

[tdonohue]

Per today's meeting, assigning this to Atmire (as requested by @lieven-atmire ). I've tentatively assigned to @artlowel , but feel free to delegate or reassign.

[artlowel]

Rather than adding contextual help icons everywhere, I propose we hide them by default, and add a single icon to the header to show them. That would be the question mark icon in this screenshot:

So before clicking the button the home page might look like this:

Clicking the button adds little icons to each component that has contextual help:

Clicking these icons will show the help in a tooltip:

I opted not to show all these tooltips when clicking the initial icon in the header, because they might overlap, and a user is likely to be interested in one or more, but not all tooltips.

The tooltips will show on click, not on hover, that way it will only disappear if the user makes the conscious decision to close it

Contextual help will be added in the i118n messages files. It will be possible to add line breaks, but no markup in the first iteration. Later we can consider adding e.g. markdown support, but I left it out for now in order not to overcomplicate things.

Adding contextual help to a component will happen using a custom directive:

<h2 *dsContextHelp="'context-help.multi-para.test'">{{'home.top-level-communities.head' | translate}}</h2>

This means it can be added to most tags, with a few exceptions because the directive will need to add the HTML for the icon and tooltip above the tag you add the directive to. So adding it to e.g. an <li> will result in invalid HTML. But there's usually ways around that, for example by adding a <span> around the contents of the <li> and adding the directive to that <span> instead.

It will be possible to specify the placement of the question mark icon (left, right) as well as as the tooltip (left, right, top, bottom)

Implementing this directive and adding a few example bits of contextual help will take about 40 hours.

Note that this does not include writing contextual help for everything, which can happen in later PRs by anyone.