Tooltip Guidelines #76261
Labels
No Label
Interest
Alembic
Interest
Animation & Rigging
Interest
Asset Browser
Interest
Asset Browser Project Overview
Interest
Audio
Interest
Automated Testing
Interest
Blender Asset Bundle
Interest
BlendFile
Interest
Collada
Interest
Compatibility
Interest
Compositing
Interest
Core
Interest
Cycles
Interest
Dependency Graph
Interest
Development Management
Interest
EEVEE
Interest
EEVEE & Viewport
Interest
Freestyle
Interest
Geometry Nodes
Interest
Grease Pencil
Interest
ID Management
Interest
Images & Movies
Interest
Import Export
Interest
Line Art
Interest
Masking
Interest
Metal
Interest
Modeling
Interest
Modifiers
Interest
Motion Tracking
Interest
Nodes & Physics
Interest
OpenGL
Interest
Overlay
Interest
Overrides
Interest
Performance
Interest
Physics
Interest
Pipeline, Assets & IO
Interest
Platforms, Builds & Tests
Interest
Python API
Interest
Render & Cycles
Interest
Render Pipeline
Interest
Sculpt, Paint & Texture
Interest
Text Editor
Interest
Translations
Interest
Triaging
Interest
Undo
Interest
USD
Interest
User Interface
Interest
UV Editing
Interest
VFX & Video
Interest
Video Sequencer
Interest
Virtual Reality
Interest
Vulkan
Interest
Wayland
Interest
Workbench
Interest: X11
Legacy
Blender 2.8 Project
Legacy
Milestone 1: Basic, Local Asset Browser
Legacy
OpenGL Error
Meta
Good First Issue
Meta
Papercut
Meta
Retrospective
Meta
Security
Module
Animation & Rigging
Module
Core
Module
Development Management
Module
EEVEE & Viewport
Module
Grease Pencil
Module
Modeling
Module
Nodes & Physics
Module
Pipeline, Assets & IO
Module
Platforms, Builds & Tests
Module
Python API
Module
Render & Cycles
Module
Sculpt, Paint & Texture
Module
Triaging
Module
User Interface
Module
VFX & Video
Platform
FreeBSD
Platform
Linux
Platform
macOS
Platform
Windows
Priority
High
Priority
Low
Priority
Normal
Priority
Unbreak Now!
Status
Archived
Status
Confirmed
Status
Duplicate
Status
Needs Info from Developers
Status
Needs Information from User
Status
Needs Triage
Status
Resolved
Type
Bug
Type
Design
Type
Known Issue
Type
Patch
Type
Report
Type
To Do
No Milestone
No project
No Assignees
14 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: blender/blender#76261
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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:
What tooltips should not contain:
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.
\n) and bullet points (\u2022) is fine.** 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"
** "Higher values reduce render time, lower values render with more detail."
** Don't: "Hide in Viewport"
** Do': "Show in Viewport"
** Don't: "Enables snapping during transform"
** Do: "Snap during transform"
** 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"
Changed status from 'Needs Triage' to: 'Confirmed'
Added subscriber: @WilliamReynish
#50283 was marked as duplicate of this issue
Added subscribers: @JulianEisel, @Constantina32, @JulienKaspar, @Arruda23, @PawelLyczkowski-1, @Blendify, @tiles, @DuarteRamos, @GaiaClary, @BrendonMurphy
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).
@JulianEisel: 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.
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.
Added subscriber: @Harley
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.
Added subscriber: @Imaginer
@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.
Added subscriber: @xan2622
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):
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.
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
F1for more informations about this feature".I have the feeling that new Blender users (and even sometimes, more advanced users) rarely use this
F1button. 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?
Added subscriber: @TheJanitor
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?
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.
Added subscriber: @ckohl_art
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.
Added subscriber: @HooglyBoogly
Looks good to me! I would only add one thing:
** 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.
Added subscriber: @ideasman42
Generally LGTM, re:
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.
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.
Ah, good. :)
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.
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.
Use present tense for showcasing what things are, i.e. properties
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:
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
:)
You're right. Sorry about that. I was wading through blender's tooltips, trying to find a good example, and didn't notice.
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)
Added subscriber: @Andrewm90
Some additional suggestions for Labels/Tooltips.
Acronymns in Labels/Tooltips should be in Uppercase.
Clarification on the use of Show/Display in tooltips.