Why Business Glossaries Fail and How to Build One That Gets Used

Every data catalog implementation includes a business glossary. Almost none of them are used six months after launch. The data engineering team writes some definitions during implementation, the project gets declared done, and the glossary slowly fossilizes into a list of outdated terms that no one trusts. The problem is not that business glossaries are a bad idea. It is that they are built the wrong way.

Why Most Business Glossaries Fail

Written by the wrong people: The most common failure mode is a data engineering team writing business definitions for business terms. A data engineer knows how the revenue column is computed — which tables are joined, which filters are applied. They do not know whether the revenue figure in the column matches what the finance team presents to the board, or whether there is a reconciliation step that happens in Excel after the data is extracted. Business definitions need to be written and certified by the business owners who use the data to make decisions.

Not connected to the data: A Confluence page with a list of metric definitions is not a business glossary — it is documentation. A business glossary that is actionable connects each definition to the specific columns in specific tables that implement that definition. When a data engineer queries the revenue column and sees it tagged with the certified finance definition, they have operational context. When they have to look up the definition in a separate system, they usually do not bother.

No maintenance workflow: Definitions are written once and never updated when the underlying calculations change. A churn rate definition written when the product had two subscription tiers becomes inaccurate when a third tier is introduced. Without a change workflow that triggers definition review when the underlying columns change, glossaries decay continuously.

No trust signal: Without certification status, users cannot distinguish between a carefully maintained definition and one that was written as a placeholder three years ago. A glossary where everything looks equally authoritative is not trusted, because users cannot tell what is reliable.

The Design Principles of a Glossary That Gets Used

Business owners write and certify definitions: The finance analyst certifies the revenue definition. The growth PM certifies the activation metric definition. The data engineering team's role is to surface the column, auto-generate a draft definition from transformation logic, and route it to the appropriate business owner for review and certification. This creates real accountability and ensures definitions reflect business intent rather than technical implementation.

Definitions are linked to columns: Every certified term maps to one or more columns in one or more tables. The mapping is visible in both directions: from the glossary term to the implementing columns, and from each column to any glossary terms it implements. Engineers and analysts who encounter a column can immediately see whether it is defined in the glossary, who certified the definition, and when it was last reviewed.

Change triggers review: When a column that implements a certified glossary term changes — schema change, significant volume anomaly, or dbt model logic update — the system automatically flags the associated definition for re-certification. The business owner gets a notification: "The underlying data for this metric has changed. Please review and re-certify the definition." This transforms the glossary from a static document into a living record of business knowledge.

Trust signals are explicit: Every definition is explicitly tagged as Certified, Draft, or Review Required. Certified means a designated business owner has reviewed and approved the definition within the past review cycle. Draft means a definition exists but has not been certified. Review Required means the definition was previously certified but has been flagged for re-certification due to a change in the underlying data. Users can see immediately whether the definition they are reading is authoritative.

Getting Business Owners to Participate

The practical challenge is getting finance analysts, growth PMs, and other business owners to engage with a data tool. Most business owners are not data engineers and do not want to log into a data catalog platform to review definitions. The certification workflow needs to meet them where they already are.

The most effective approach is email-based certification with a preview: the business owner receives an email showing the current definition and the column it maps to, with a one-click "Certify" button that records their approval without requiring them to navigate to the platform. For definitions that need revision, the email includes a link to an edit interface that is simple enough for non-technical users. The data engineering team handles the platform; the business owners handle the definitions through a lightweight email workflow.

How Decube Implements the Business Glossary

Decube's glossary is built as a first-class feature alongside lineage and quality monitoring, not as an afterthought. Column definitions are surfaced directly in the lineage graph — when you click on a column node, you see its lineage upstream and downstream, its current quality status, and its glossary definition (if certified). The draft generation uses column names, transformation logic, and any existing dbt descriptions to produce a starting point that business owners can edit rather than write from scratch.

Certification notifications are delivered via email and Slack. Re-certification is triggered automatically when quality monitors detect significant changes to columns that implement certified glossary terms. The trust signals (Certified, Draft, Review Required) appear consistently throughout the platform wherever column information is displayed.