Feature Request: Tool Tip integration with Docs

[Abejithp]

Motivation

Currently, Superset's tooltip messages do not provide any correlation to the documentation or FAQ, and definitions are scattered across the codebase. This separation creates challenges in maintaining consistency, improving discoverability, and helping new users understand key concepts directly from the UI.

A unified approach between tooltips and documentation would help ensure that shared definitions and terminology stay synchronized while reducing maintenance overhead for contributors.

Proposed Solution

We propose introducing a new Glossary system that connects Superset's in-product tooltips with the documentation site. A new Glossary section would be added to the documentation to display definitions for the most common tooltip descriptions. This glossary would be dynamically generated from a shared data source, ensuring that the same definitions appear in both the UI and the docs.

Implementation Steps

1. Create a glossary.json file

   • Define tooltip messages and short definitions for all relevant UI components.
   • Serve as a single source of truth for shared explanatory content.

2. Update the documentation build

   • Automatically consume and render the glossary.json content in a new Glossary section.
   • Provide clear, searchable definitions for users and developers.

3. Implement a Tooltip Wrapper Component

   • Build a reusable React wrapper that fetches tooltip messages from the glossary.json.
   • Ensure localization support remains intact and simple to extend.

4. Enhance Existing Tooltips

   • Update existing tooltips to indicate related documentation (e.g., “Read more” or “View in docs”).
   • Allow tooltips to optionally link directly to relevant documentation or glossary entries.

Scope

The tooltip integration aims to cover all existing tooltips within Superset.

Given the wide scope, a codemod could be introduced to help automate the migration process, converting existing static tooltip messages to use the new wrapper class and shared glossary entries efficiently.

Benefits

This enhancement will:

• Unify documentation and in-product messaging for consistent definitions.
• Improve discoverability by linking users directly from tooltips to relevant documentation.
• Simplify maintenance by consolidating tooltip text and definitions into a single managed source.
• Enhance accessibility and onboarding, helping new users understand key terms and features more easily.

Ultimately, this integration creates a more cohesive experience for both users and developers, ensuring that Superset’s UI and documentation evolve together.

Feedback and additional ideas are very welcome!