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 [[link|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 [[link|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"
- Limit Surface
- 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"