Tooltip Guidelines #76261

New Issue

William Reynish · 2020-04-30T13:55:33+02:00

William Reynish commented

2020-04-30 13:55:33 +02:00

In Blender, many of our tooltips are useless, and don't convey any extra information that the name doesn't already communicate.

These tooltips are useless for the people who need them, for the cases where it isn't exactly clear what the feature does

Additionally, tooltips are often worded differently. Sometimes the tooltip tells users what will happen when the option is disabled rather than enabled:

Examples of tooltips that don't adhere to these guidelines can be posted here: https://devtalk.blender.org/t/bad-tooltips-thread/7048

Current Proposal

(Links removed)

General rules

Follow the general writing style guidelines.

What tooltips should contain:

The name of the item, not followed by a period. (Automatically added in most tooltips for RNA properties and operators.)
A description of the item (see below).
A "disabled hint" for disabled buttons: If a button is disabled, this text will explain why. (TODO document how to set this!).
The shortcut, if any.
The library path, if any.
Additional useful information (expressions for drivers, BPY path, etc. - These fields may be automatically generated and may be disabled through a Preference option).

What tooltips should not contain:

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

The tool description

Tooltips should first and foremost be helpful. If more than a short sentence is needed to achieve that, by all means, use more than one. Yet, try to keep it short. In other words: Short and to the point.

Do not use more than a couple of lines, try to stick with two or three.
Use full sentences with normal punctuation.
Formatting with new lines (\n) and bullet points (\u2022) is fine.
It's fine to mention examples of situations where you might use the tool.
Avoid using the described term to explained itself.
** Limit Surface
*** Don't: "Put vertices at the limit surface"
*** Do: "Place vertices at the surface that would be produced with infinite levels of subdivision (smoothest possible object)".
** Proportional Editing
*** Don't: "Enable Proportional Editing"
*** Do: "Proportional Editing: Transform the neighbouring elements in a falloff from the selection"
Explanations of how the result is affected by different values are fine.
** "Higher values reduce render time, lower values render with more detail."
Only describe the ''positive'' state of a toggle, not the negative
** Don't: "Hide in Viewport"
** Do': "Show in Viewport"
Do not use redundant words such as "enables", "activates" etc.
** Don't: "Enables snapping during transform"
** Do: "Snap during transform"
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"

In Blender, many of our tooltips are useless, and don't convey any extra information that the name doesn't already communicate. ![Screenshot 2020-04-29 at 22.51.47.png](https://archive.blender.org/developer/F8502828/Screenshot_2020-04-29_at_22.51.47.png) ![Screenshot 2020-04-29 at 22.45.49.png](https://archive.blender.org/developer/F8502830/Screenshot_2020-04-29_at_22.45.49.png) These tooltips are useless for the people who need them, for the cases where it isn't exactly clear what the feature does Additionally, tooltips are often worded differently. Sometimes the tooltip tells users what will happen when the option is disabled rather than enabled: ![Screenshot 2020-04-29 at 23.11.57.png](https://archive.blender.org/developer/F8502832/Screenshot_2020-04-29_at_23.11.57.png) Examples of tooltips that don't adhere to these guidelines can be posted here: https://devtalk.blender.org/t/bad-tooltips-thread/7048 ---- # Current Proposal (Links removed) ## General rules Follow the general [writing style guidelines](link). What tooltips should contain: * The name of the item, not followed by a period. (*Automatically added in most tooltips for RNA properties and operators.*) * A description of the item (see [below](link)). * A "disabled hint" for disabled buttons: If a button is disabled, this text will explain why. (TODO document how to set this!). * The shortcut, if any. * The library path, if any. * Additional **useful** information (expressions for drivers, BPY path, etc. - *These fields may be automatically generated and may be disabled through a Preference option*). What tooltips should **not** contain: * Code snippets. * Anything with very involved details (e.g. troubleshooting, corner cases that might not work, etc.). ## The tool description Tooltips should first and foremost be helpful. If more than a short sentence is needed to achieve that, by all means, use more than one. Yet, try to keep it short. In other words: Short **and** to the point. * Do **not** use more than a couple of lines, try to stick with two or three. * Use full sentences with normal punctuation. * Formatting with new lines (`\n`) and bullet points (`\u2022`) is fine. * It's fine to mention examples of situations where you might use the tool. * Avoid using the described term to explained itself. ** *Limit Surface* *** ***Don't**: "Put vertices at the limit surface"* *** ***Do**: "Place vertices at the surface that would be produced with infinite levels of subdivision (smoothest possible object)".* ** *Proportional Editing* *** ***Don't**: "Enable Proportional Editing"* *** ***Do**: "Proportional Editing: Transform the neighbouring elements in a falloff from the selection"* * Explanations of how the result is affected by different values are fine. ** *"Higher values reduce render time, lower values render with more detail."* * Only describe the ''positive'' state of a toggle, **not** the negative ** ***Don't**: "Hide in Viewport"* ** ***Do**': "Show in Viewport"* * Do **not** use redundant words such as "*enables*", "*activates*" etc. ** ***Don't**: "Enables snapping during transform"* ** ***Do**: "Snap during transform"* * 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"*

William Reynish commented

2020-04-30 13:55:33 +02:00

Changed status from 'Needs Triage' to: 'Confirmed'

William Reynish commented

2020-04-30 13:55:33 +02:00

Added subscriber: @WilliamReynish

blender-admin commented

2020-04-30 13:55:33 +02:00

#50283 was marked as duplicate of this issue

Julian Eisel commented

2020-04-30 14:03:46 +02:00

Added subscribers: @JulianEisel, @Constantina32, @JulienKaspar, @Arruda23, @PawelLyczkowski-1, @Blendify, @tiles, @DuarteRamos, @GaiaClary, @BrendonMurphy

Julian Eisel commented

2020-04-30 14:17:09 +02:00

I'd like to push hard for disabled hints. That is, showing why a button is disabled in the tooltip.
(Here the hint could be made more clear actually)

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).

I'd like to push hard for disabled hints. That is, showing why a button is disabled in the tooltip. ![tooltip_disabled.png](https://archive.blender.org/developer/F8503095/tooltip_disabled.png) *(Here the hint could be made more clear actually)* 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).

William Reynish commented

2020-04-30 15:07:04 +02:00

@JulianEisel: would be good if we could automate that, if possible.

Duarte Farrajota Ramos commented

2020-04-30 16:43:29 +02:00

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 #76261#920786, @JulianEisel 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.

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 #76261#920786, @JulianEisel 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.

Harley Acheson commented

2020-04-30 20:57:31 +02:00

Added subscriber: @Harley

Harley Acheson commented

2020-04-30 20:57:32 +02:00

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.

Ryan Inch commented

2020-05-01 03:32:01 +02:00

Added subscriber: @Imaginer

Ryan Inch commented

2020-05-01 03:32:01 +02:00

@JulianEisel 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 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.

@JulianEisel 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 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.

xan2622 commented

2020-05-01 22:10:07 +02:00

Added subscriber: @xan2622

xan2622 commented

2020-05-02 15:14:47 +02:00

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 [ https:*www.keycdn.com/support/png-to-webp | .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.

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 [[ https:*www.keycdn.com/support/png-to-webp | .WebP ](https:*techstacker.com/why-webm-is-superior-to-gif-video-comparison/FR6xLr2zHn9uSTTsH/)) 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 ](https://docs.blender.org/manual/en/latest/) ? 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.

Brendon Murphy commented

2020-05-04 00:14:44 +02:00

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?

Adrian Newton commented

2020-05-05 11:24:43 +02:00

Added subscriber: @TheJanitor

Adrian Newton commented

2020-05-05 11:24:43 +02:00

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

For example:

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.
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 , if

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

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?

Adrian Newton commented

2020-05-15 17:09:37 +02:00

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.

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.

Chris Kohl commented

2020-08-31 21:34:37 +02:00

Added subscriber: @ckohl_art

Julian Eisel commented

2020-09-23 17:43:09 +02:00

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.

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.

Hans Goudey commented

2020-09-23 18:00:03 +02:00

Added subscriber: @HooglyBoogly

Hans Goudey commented

2020-09-23 18:00:03 +02:00

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)

Looks good to me! I would only add one thing: * Use the imperative tense to describe what a property does ** **Don't**: "Determine**s** 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)`

Julian Eisel commented

2020-09-23 18:14:07 +02:00

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.

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.

Campbell Barton commented

2020-09-24 02:19:51 +02:00

Added subscriber: @ideasman42

Campbell Barton commented

2020-09-24 02:19:51 +02:00

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.

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.

Ryan Inch commented

2020-09-24 04:57:47 +02:00

In #76261#1021794, @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 @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 #76261#1021794, @HooglyBoogly wrote: > Looks good to me! I would only add one thing: > > * Use the imperative tense to describe what a property does > ** **Don't**: "Determine**s** how the geometry end factor is mapped to a spline" > ** **Do**: "Determine how the geometry end factor is mapped to a spline" Um, sorry @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.

Hans Goudey commented

2020-09-24 06:15:04 +02:00

In #76261#1022094, @Imaginer wrote:
Um, sorry @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.

> In #76261#1022094, @Imaginer wrote: > Um, sorry @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.

Ryan Inch commented

2020-09-24 09:09:12 +02:00

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.

> 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.

Hans Goudey commented

2020-09-24 16:20:34 +02:00

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..."

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..."

Aaron Carlisle commented

2020-09-24 21:21:34 +02:00

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"

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"

Duarte Farrajota Ramos commented

2020-09-24 23:34:42 +02:00

In #76261#1022795, @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

> In #76261#1022795, @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

Ryan Inch commented

2020-09-25 08:51:36 +02:00

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)

> 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)

Andy Sellers commented

2020-09-28 20:42:02 +02:00

Added subscriber: @Andrewm90

Adrian Newton commented

2020-09-30 12:46:42 +02:00

Some additional suggestions for Labels/Tooltips.

Acronymns in Labels/Tooltips should be in Uppercase.
Clarification on the use of Show/Display in tooltips.

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.

Philipp Oeser removed the

Interest

User Interface

label 2023-02-10 09:24:29 +01:00

~~Alaska referenced this issue 2024-08-24 16:14:57 +02:00~~

UI: Add missing tooltips to Principled BSDF for Sheen and Thin Film #126735

Sign in to join this conversation.

14 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: blender/blender#76261

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Tooltip Guidelines #76261

Current Proposal

General rules

The tool description