Tooltips

Tooltips are little popups that give more information about the element under the mouse cursor.

General rules

Follow the general writing style guidelines.

What tooltips should contain:

• The name of the item, not followed by a period
• 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)

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

• It is recommended to start descriptions with verbs. Using the imperative conjugation generally works best.
  Don't: "The factor determines how the geometry end factor is mapped to a spline"
  Do: "Determine how the geometry end factor is mapped to a spline"
• Do not use more than a couple of lines, try to stick with two or three.
• Do not end the description with a period, unless there are multiple sentences.
• It's fine to mention examples of situations where you might use the tool.
• Do not document default values; these can change and are hard to keep updated.
• Do not use the described term to explain 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: "Transform the neighbouring elements in a falloff from the selection"
• Explanations of how the result is affected by different values are fine.
  For example: "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"