Tooltip Guidelines
Open, NormalPublic

Description

Tooltip Guidelines

As part of the 2.8 UI workshop, we agreed on having tooltip guidelines to ensure useful and high quality tooltips: https://wiki.blender.org/index.php/Dev:2.8/UI/Workshop_Writeup#Tooltips
An initial guideline page can be found here https://wiki.blender.org/index.php/Dev:Doc/Projects/UI/Tooltip_Guidelines. This task should be used to discuss and finalize it.

Once the page is finalized, we'll ask all contributors to follow it strictly.

Details

Type
Design

hi, great initiative, some small changes & comments:

General rules
What tooltips May contain

The name of the tool
A description of the tool

(Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements

If a button is disabled, the tooltip should always show useful information on why it is disabled and ideally how to change that.

Indeed, example of this will be in booltools addon release within a few days.
Tooltip Line 1: Please select 2 or more mesh objects
Tooltip Line 2: Boolean Operation to join the mesh (Union)

Additional useful info (Shortcuts, Python path, etc, that are Automatically generated)

The tool description:

The description of the tool should basically be short and to the point. But there are more rules to follow:

Do not use more than 2 lines or 3 only in the case of adding a hotkey that is not auto generated.
Use full sentences (periods and commas are allowed).
Examples of situations where you might use the tool are allowed.
Avoid using the described term to explained itself.

there should also be a character limit applied, some tool tips can get incredibly long

What tooltips should not contain

Code snippets
Anything with very involved details (e.g. troubleshooting, corner cases that might not work, etc.)

+1

These guidelines will also apply to addons.

I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way.

Would it be possible to have 2 tool tips for each item?

description = "contains information when the item is operable."
disablehint = "contains information when the item is disabled."

When disablehint is not defined, then description is used
And of course the naming is just a placeholder for something better :)

(Description is better than just the name & really no need for both, the button or menu is already the name) EDIT: with the exception of Icon Only ui elements

Indeed, there isn't a need to show the tool name in most cases, a short, general description would be enough, followed by a more detailed description. Kind of like we do currently already. E.g.


Also, I realize "tool name" is the wrong term, we're actually talking about the name of the entity a button represents (can be an operator, property or a enum-property value).

I also have a concern with Pie Menus & Tooltips, they get in the way of the menus and are quite distracting, maybe we need an option to disable tooltips for pie menus? Tooltips are useful, just in this case they do really get in the way.

It's a bit tricky to solve that. What we could do is make tooltips follow the radial layout. Meaning for a button at the left, the tooltip would appear on its left side (if enough space is available), for a button at the top, the tooltip would appear above it, etc.

Would it be possible to have 2 tool tips for each item?

description = "contains information when the item is operable."
disablehint = "contains information when the item is disabled."

When disablehint is not defined, then description is used
And of course the naming is just a placeholder for something better :)

The info on why a button is disabled (and how to fix that?) should always be additional info, when showing it, the normal button description should still be visible.
Since rB6f8060450, we can already return a string in RNA _editable callbacks containing info on why the button is disabled. Operators can also store such strings through CTX_wm_operator_poll_msg_set. These strings are then displayed in tooltips.
So these approaches allow context-sensitive usage and thus are a bit more dynamic than just storing a fixed description for an item for the case that it's disabled. I think that's the right direction to go, for Python we should do something similar.

Icon only buttons would need the tool name too.

For 2.8 I purpose that by default we disable developer information in tooltips. This will make the tooltips look simpler and also follows the proposal of "no code snippets" What will also help tooltips is the adjust the styling a little. For example, a while ago @Paweł Łyczkowski (plyczkowski) made this mockup but it got lost: