I'd like to push hard for disabled hints. That is, showing why a button is disabled in the tooltip.

We'd need some more changes to support this everywhere, but I see this as a great usability feature. Often when I see a disabled button in an application I have no clue why it's disabled, and I wish it had such a hint.
IMHO the guidelines should explicitly say that this should be always be done when disabling items (assuming we make it technically possible).

@Julian Eisel (Severin): would be good if we could automate that, if possible.

I'll be very glad to see improvements in this area, one of the places where this bothered me the most is shader node properties that just read Input value for unconnected socket, rather than a describing what they do.

In T76261#920786, @Julian Eisel (Severin) wrote:

I'd like to push hard for disabled hints. That is, showing why a button is disabled in the tooltip.

I second this, especially for complex Edit Mode operators that require a particularly delicate element selections.

What is your stance on including how numerical values affect performance and/or quality in tooltips?

Most properties improve quality at the expense of performance/resources when numerical values increase, but some exceptions exist, mostly in properties relating to densities, steps or interpolations that work the other way around.
Things like say Voxel Size in the Remesh Modifier or Tiles/Steps for volumetrics among others.

Would you consider, where relevant, including in the tooltips how the values relate to performance and quality? Something along the lines of: "Higher value > better quality > more resources", or "Lower value > worse quality > faster render".
These are often relevant because sometimes tweaking some properties is slow (while something heavy is recalculated), has invisible or no immediate feedback, requires very large numeric changes to have visible effect or is very sensitive to small adjustments, and increasing them too high may lead to unresponsive Blender or worse a crash.

I understand these are intrinsically very verbose there is the concern that can make tooltips rather large and unreadable. They are also hard to summarize and word concisely.
Maybe if they could somehow be hidden behind "expanded tootip" that would show up only at user discretion, behind some "expand" button or an optional toggle.

It is probably worth considering and mentioning the use of multi-line tooltips. They are supported. Just add "\n" to make it wrap. Doing so can potentially allow more details in them without making a long mess. You could even add bullet points. But the automatic inclusion of that final "." does screw up some potential uses. For example while in the File Browser you could use tooltips to give access to some of the information not visible while in thumbnail view, like file size and modified date. But if you try doing that nicely with a multi-line tip that terminal period looks a bit silly.

@Julian Eisel (Severin) How do you add a disabled hint to a tooltip in python? I'd like to add some to my addon, but can't find any references as to how to accomplish this.

@Harley Acheson (harley) I've done that with some tooltips, bullet points and all, but there is a hard cut off of somewhere around 235 characters, so watch out for that.

I noticed in the bad tooltips thread that there were requests for dynamic tooltips based on operator arguments. Most people here probably know this, but for any who don't, this is possible by adding a description method to the operator.

There have been several suggestions to add more informations into tooltips (in the current tooltips or displayed in "advanced" tooltips, which would be accessible with a modifier key):

• Support for image/gifs/videos in the interface: https://blender.community/c/rightclickselect/SRcbbc/#5eac5efb9c122101b9526d1f
• TOOLTIPS FOR BLENDER 101: https://blender.community/c/rightclickselect/f3bbbc/

I do like the idea to see images (animated or not) in tooltips (for Blender and add-ons): this extra visual information can really give quick & clear(er) explanations about features & buttons.

There's a regular concern expressed in the comments of two websites above: a possible "increased Blender installer file size".
GIFs can be a solution but other file formats (such as: .WebM or .WebP) are probably better suited for this task.

• More info about the webm file format (for animations/short movies): https://www.webmproject.org/code/
• More info about the webp file format (for static images): https://developers.google.com/speed/webp

For add-ons, as -L0Lock- said in his comment: it would be up to the add-on authors to decide if they want to add these animated images (or not).

In the meantime, maybe tooltips could be enhanced with links pointing to the Reference Manual ?

Or simpler: it could be decided to add the following sentence into tooltips: Press F1 for more informations about this feature".
I have the feeling that new Blender users (and even sometimes, more advanced users) rarely use this F1 button. Adding this sentence into tooltips would make this hotkey more known and used.

You could try Better tooltips (Basic) And extend the tooltips by adding a Manual link into the tooltip for more precise information? This would keep the tooltips smaller and not as intrusive?

A) Could there be some guidance within the tooltips for items that require items enabled/selected in other areas?

For example:

1. In the Properties Editor / World Settings / Viewport Display, you can change the Color, but the 'World' option also needs to be selected in the 3D Viewport Shading options.

2. In the Properties Editor / View Layer Properties / Light - Ambient Occlusion is greyed out until Ambient Occulsion is enabled in Render Properties.

The tool tip for Post Processing/ Compositing checkbox contains the tooltip in the form of:

Do <something>, if <condition is met>

Could this be the example of tooltip for this particular use case?

Can any furture tooltip guidance include the use of Capitalisation and possibly '' (quotes) for tooltips?

a) Capitalisation for things like Workspace, Editor and Tab names &
b) ' ' for references to variable names.

For Example:

Properties Editor / Output Properties / Post Processing

The current tooltip for Compositing is:
Process the render through the compositing pipeline, if compositing node are enabled

Could be:
Process the Render through the Compositor pipeline, if the Compositor 'Use Nodes' checkbox is enabled.

or Even
Process the RENDER through the COMPOSITOR pipeline, if the COMPOSITOR 'Use Nodes' checkbox is enabled.

Updated the description with the most recent proposal. It's the exact wording we currently have in the WIP Human Interface Guidelines.
Please don't edit it here directly, otherwise the versions may go out of sync.

I ask the UI team (esp. the core module members) to either approve or object.

Looks good to me! I would only add one thing:

• Use the imperative tense to describe what a property does
  • Don't: "Determines how the geometry end factor is mapped to a spline"
  • Do: "Determine how the geometry end factor is mapped to a spline"

The difference here is somewhat subtle, but it's jarring when there are different tenses used everywhere, and I think this the most professional and direct.

I would also suggest clarifying that the property name is added automatically to most tooltips:
The name of the item, not followed by a period. -> The name of the item, not followed by a period. (Automatically added in most tooltips for RNA properties and operators)

Good points, updated the proposal.

One could argue that the imperative thing should go to the general writing style page, but it may actually be specific to tooltips so I'll leave it there for now.

Generally LGTM, re:

What tooltips should not contain:

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

While it's a good rule of thumb. I'd be careful removing this kind of information from existing tool-tips.

If the information is important we could either keep it (if it's a border-line case that isn't too detailed), or move it to known-limitations section of the manual.

There may be some cases we want to mention there are common problems users should be aware of in the manual, although we could cross that bridge when if/when we come to it.

In T76261#1021794, @Hans Goudey (HooglyBoogly) wrote:

Looks good to me! I would only add one thing:

• Use the imperative tense to describe what a property does
  • Don't: "Determines how the geometry end factor is mapped to a spline"
  • Do: "Determine how the geometry end factor is mapped to a spline"

Um, sorry @Hans Goudey (HooglyBoogly), but I have to disagree with you here. Tooltips are meant to describe what the button will do, not instruct the user to do something (except for special cases).
According to Collins dictionary, "The imperative is used to give commands and orders" so by changing it to imperative tense you are not describing what the property does, but ordering the user to do something (in this case it's to figure out how the geometry end factor is mapped to a spline). You're right that this is a subtle difference, but it completely changes the meaning, and in the case of your example, makes it incorrect for the context it's used in.

I believe your Don't example is in present tense and that this is the correct tense for tooltips to use in most cases.

In T76261#1022094, @Ryan Inch (Imaginer) wrote:

Um, sorry @Hans Goudey (HooglyBoogly), but I have to disagree with you here. Tooltips are meant to describe what the button will do, not instruct the user to do something (except for special cases).
According to Collins dictionary, "The imperative is used to give commands and orders" so by changing it to imperative tense you are not describing what the property does, but ordering the user to do something (in this case it's to figure out how the geometry end factor is mapped to a spline). You're right that this is a subtle difference, but it completely changes the meaning, and in the case of your example, makes it incorrect for the context it's used in.

I believe your Don't example is in present tense and that this is the correct tense for tooltips to use in most cases.

No need to apologize, disagreeing is fine ;)

I think that's a backwards way of looking at it. To put it in your language, it's not the application giving orders to the user, it's the user giving orders to the application.

IMO the problem with the present tense is that it places a "phantom subject" before the sentence. So the idea becomes "This button determines how the..." instead of the direct "Determine how..."
Again it's a subtle difference, but the second one is so much more direct. It's not the button that's important but the action that would result from using it. It clearly maps to a statement of the user's desire.

Anyway, searching around on the internet for some form of "ux tooltip guidelines language" results in similar results. Although I didn't see the word "imperative" used, I mostly saw recommendations for starting tooltips describing actions with an un-conjugated verb.

No need to apologize, disagreeing is fine ;)

Ah, good. :)

IMO the problem with the present tense is that it places a "phantom subject" before the sentence. So the idea becomes "This button determines how the..." instead of the direct "Determine how..."

Arguably, the first one is still more correct because the tooltip is describing what the button/UI element does, but the direct approach is fine or possibly better depending on the context.

It's not the button that's important but the action that would result from using it. It clearly maps to a statement of the user's desire.
recommendations for starting tooltips describing actions with an un-conjugated verb.

This isn't an action we're talking about here, this is a property. For tooltips for operators, and properties that act like operators, you're describing what the action will do (and so the imperative is fine/better), but for properties that are setting a value that will control how something behaves, you're not performing an action and so the present tense is better. There is also some overlap where both approaches fit well, so some discretion should be used.

Even a general rule is hard to establish because context is so important.

A better rule might be something like this:
Use imperatives for showcasing what things do, i.e. actions/tools.

• Don't: Moves selected items.
• Do: Move the selected objects.

Use present tense for showcasing what things are, i.e. properties

• Don't:Calculate the tilt for 3D curves.
• Do: The type of tilt calculation for 3D curves.

But to be honest, during the writing of this post I've been looking through blender's various tooltips and I've been able to come up with equally good options for both imperative and non-imperative in most cases. English is not simple. :P
In the end I think the most important thing is to make sure the tooltips are clear and informative.

Yes, I like the way you've clarified "What things to" vs "What things are". However, I'd point out that your second "Do" is not in any tense at all, there is no verb. But I agree it's better than the "Don't". Not everything should be phrased as an action.

I agree that it's usually possible to phrase descriptions as both an action and a thing. The "imperative guideline" should probably read, "When a tooltip is phrased as an action..."

An area we are not quite consistent is using a leading article or not (a/an, the). E.g:

• "Bevel Depth", "Size of the bevel geometry when not using the object bevel mode"
• "Bevel Depth", "The size of the bevel geometry when not using the object bevel mode"

In T76261#1022795, @Aaron Carlisle (Blendify) wrote:

An area we are not quite consistent is using a leading article or not (a/an, the). E.g:

• "Bevel Depth", "Size of the bevel geometry when not using the object bevel mode"
• "Bevel Depth", "The size of the bevel geometry when not using the object bevel mode"

I'd definitely leave it out, its just visual noise in the way of the actual content.
Takes longer to read and doesn't improve clarity in any way

Yes, I like the way you've clarified "What things to" vs "What things are".

:)

However, I'd point out that your second "Do" is not in any tense at all, there is no verb.

You're right. Sorry about that. I was wading through blender's tooltips, trying to find a good example, and didn't notice.

I agree that it's usually possible to phrase descriptions as both an action and a thing. The "imperative guideline" should probably read, "When a tooltip is phrased as an action..."

Sure. What I think is most important is clear communication, so whatever best achieves that I'll support. (It turns out I've used imperatives in tooltips myself, but I never really noticed until now. Lol)

Some additional suggestions for Labels/Tooltips.

1. Acronymns in Labels/Tooltips should be in Uppercase.

2. Clarification on the use of Show/Display in tooltips.