Bring consistency to the tooltips of the toolbar actions

[GabrielaVives]

Problem

The tooltips of the toolbar actions are either inconsistent, or do not correctly represent the action they represent.
For example, some refer to "cells" even though the action will apply only to one cell. This can create misunderstandings for new users, and can be easily fixed.

Proposed Solution

Change the tooltips as in the illustration below:

(With the keyboard shortcuts between the brackets at the end of each tooltip).

Additional context

Providing short and explicit tooltips is always necessary when a button does not have an explicit title, as for icons. Here, some UX basic rules are not followed but require a very low effort to significantly improve the user experience.

Here are some rules we should follow, that I illustrated in the suggestion above:

• Use first letter upper case only
• Be short: if possible, no more than 3 words
• Provide the keyboard shortcut if it exists
• Be consistent between 2 opposite actions

[krassowski]

I think the convention is Title Case for labels and Upper case for captions.

As mentioned on the triage meeting, it is because some commands define both label and caption while others only define a label (and we use caption if available and otherwise the label), for example notebook:insert-cell-below implements both:

jupyterlab/packages/notebook-extension/src/index.ts

Lines 2338 to 2350 in 6efbd56

	commands.addCommand(CommandIDs.insertBelow, {
	label: trans.__('Insert Cell Below'),
	caption: trans.__('Insert a cell below'),
	execute: args => {
	const current = getCurrent(tracker, shell, args);
	if (current) {
	return NotebookActions.insertBelow(current.content);
	}
	},
	icon: args => (args.toolbar ? addBelowIcon : undefined),
	isEnabled
	});

but notebook:insert-cell-above only implements label:

jupyterlab/packages/notebook-extension/src/index.ts

Lines 2326 to 2337 in 6efbd56

	commands.addCommand(CommandIDs.insertAbove, {
	label: trans.__('Insert Cell Above'),
	execute: args => {
	const current = getCurrent(tracker, shell, args);
	if (current) {
	return NotebookActions.insertAbove(current.content);
	}
	},
	icon: args => (args.toolbar ? addAboveIcon : undefined),
	isEnabled
	});

This can be fixed by ensuring that all relevant commands have consistent captions.

For "duplicate cells" command, the "selection" bit can be relevant as it defined the behaviour when multiple cells are selected. We could assign a function to caption and only mention "selection" when multiple cells are indeed selected.

[GabrielaVives]

Thank you for looking in to this!

I didn't know what label and caption refer to inside the code, or what conventions are used. If it could follow the UX convention to use lower case for tooltips (except the first letter of course), that would be great. So that from the user's point of view, everything looks consistent.

For further information, here is the material design documentation on tooltips explaining what the best practices are.

[fcollonval]

cc @HaudinFlorence

[HaudinFlorence]

I am looking at this issue and opened this PR #13861.

[JasonWeill]

Related: in PR #13939, I added captions to several commands that were used in toolbar buttons and that didn't have captions. A label is typically written in Title Case without articles (e.g., "Interrupt Kernel") and a caption is typically written in sentence case with articles (e.g., "Interrupt the kernel").