Tooltip & Help Text Writing

Tooltips should add value beyond the label — explain the why or the benefit, not just restate the label.

Tooltip writing guidelines:
• Maximum ~15 words — tooltips are scanned, not read
• Explain benefit/outcome ("why do this"), not just definition
• Don't repeat the label word-for-word — that's redundant
• Avoid dry technical definitions — speak to user goals

Option A — dictionary definition; too long; creates more questions than it answers
Option B — restates the obvious ("toggle this switch to enable/disable"); no added value
Option C ✓ — explains what it does ("second verification step") and why ("recommended")
Option D — too short; gives no information

Key vocabulary:
• Tooltip — a small contextual popup that appears on hover over a UI element
• Benefit copy — text that explains why a feature matters, not just what it is
• Label redundancy — tooltip text that just repeats the element's label (an anti-pattern)
• Contextual help — inline or overlay help that appears in context of the relevant UI element

Help text for technical fields should answer: where to find it, what it looks like, and a key gotcha.

The three jobs of API key help text:
1. Where — "Found in Settings → API → Your keys" (navigation path)
2. What it looks like — "Starts with sk-" (reduces wrong-paste errors)
3. Critical warning — "Keep it private" (security nudge at the moment of use)

Option A — states the obvious; adds no new information
Option B — technical definition the user doesn't need; doesn't help them find it
Option C — better, but missing the security warning
Option D ✓ — all three jobs covered in one short line

Key vocabulary:
• Help text — persistent text below or beside a form field (visible without hover)
• Navigation path — step-by-step direction using UI labels (Settings → API → Keys)
• Contextual security nudge — brief inline warning about sensitive actions or data
• Hint text — placeholder or label that shows the expected format inside the field

Technical field help text should answer: what goes here, what technical requirements does it have, and show an example.

Three parts of excellent technical help text:
1. Plain-language description — "where we'll send event notifications"
2. Technical requirement — "must accept POST requests" (prevents a common misconfiguration)
3. Example — a plausible example reduces copy-paste errors and clarifies format

Option A — textbook definition; doesn't actually help the user fill in the field
Option B — too short; doesn't explain requirements
Option C ✓ — all three parts present
Option D — label annotation, not help text

Key vocabulary:
• Technical requirement — constraints the input must meet (e.g., "must accept POST")
• Example value — a representative value that shows the expected format
• Misconfiguration prevention — help text written to prevent the most common user errors
• Field-level documentation — contextual technical explanation at the point of configuration

Icon button labels and tooltips should be concise action phrases — not descriptions of the icon, not verbose sentences.

Good icon label formula: [Action verb] + [specific object]
• "Download as CSV" — verb (Download) + specific format (CSV)
• Short enough for a tooltip
• Descriptive enough for a screen reader announcement

Option A ("Down") — describes icon direction, not the action
Option B ("Arrow") — describes the icon itself, completely unhelpful
Option C — too verbose for a tooltip; screen readers should be concise too
Option D ✓ — perfect: action + specific outcome

Key vocabulary:
• aria-label — accessible name for UI elements without visible text labels
• Icon button — a button with only an icon (no visible label text)
• Action phrase — a label that describes what the button does, not what it looks like
• Accessible name — the label announced by screen readers for interactive elements

Tooltips over relative timestamps should provide the exact absolute value — that's their sole job.

The relative display ("3 days ago") is optimized for quick reading. The tooltip exists specifically to provide:
• Full date AND time
• Timezone (UTC or local — whichever is more useful for the audience)
• A specific, unambiguous absolute timestamp

Options A, B — no actual data; just labels for what the user already sees
Option C ✓ — provides the exact information the relative display withholds
Option D — just restates the relative value in different words; adds no information

Key vocabulary:
• Relative timestamp — human-readable time relative to now ("3 days ago")
• Absolute timestamp — a specific date and time value (Thu, 12 Jun 2025 at 14:32 UTC)
• Progressive disclosure — showing summary info by default with detail on demand (hover)
• Tooltip data reveal — using tooltip to expose the precise underlying value behind a formatted display