Page MenuHome

Tooltip Guidelines
Confirmed, NormalPublicDESIGN

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.

Event Timeline

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:

Hi guys. I'm trying to do an addon that will show an specific brush in an animated gif tooltip. This is what I have so far

Do you think this could be useful for the new users? I'm just doing for increase my knowledge in Python and Blender API, but you guys think it would be any helpful to have in the software?

@Mateus Arruda (Arruda23): would it be useful? Yes. Some other apps do this kind of thing. Should we include this by default? Not sure.

There’s an aversion to adding too much data in the Blender binary, although I think it might be nice.

Related question is, how deep should that concept go? Just for brushes? All active tools? Any tooltip?

@William Reynish (billreynish)

I was also thinking about this for a while and I definitely believe that adding images or even animated images would be very helpful for specific options that are hard to explain with text only.
Concepts like the "sculpt plane orientation" for example are not understood by most users since it's an aspect to a brush that is invisible to the user.
But I wouldn't add extra images to the vast majority of tooltips.

Hello again. I've been developing the addon I just mentioned above and I finished. I had a lot of struggles with blender addon structure and native methods such as modal, execute, poll, etc. but that's because I'm noob at programming and I also learned a lot. Here is how it looks like now:

I want to say that I did this focusing on new users experience but it is not very useful since the new user would have to install the addon and activate it to use. But I want to leave this work as an idea if the developers want to implement it natively into the software, since I used third party libraries to do so (I think this made things even more complicated).

This is the project link if anyone wants to check it out.