Documentation & Definitions — Document definitions and...

SECTION 1

Historical Context & Motivation

The need for formal data documentation predates modern analytics platforms by decades. As early as the 1960s, organizations maintaining large COBOL-based record systems realized that without a centralized catalog explaining what each field meant, developers would write conflicting queries against the same dataset. The emergence of relational databases in the 1970s sharpened this problem: a column named revenue could mean gross revenue, net revenue, or recognized revenue depending on who created the table. The proliferation of self-service business intelligence tools—culminating in platforms like Tableau—democratized data access but also multiplied the risk of inconsistent interpretation, making formal documentation an essential governance practice rather than an optional nicety.

1970s

Relational Model & Early Data Dictionaries

E.F. Codd's relational model introduced formal schemas, prompting organizations to maintain metadata catalogs—precursors to modern data dictionaries—to describe columns, types, and constraints.

1990s

Data Warehousing & Star Schemas

Ralph Kimball's dimensional modeling emphasized the importance of conformed dimensions and conformed facts, formalizing metric definitions across business units to enable consistent reporting.

2003

Tableau Founded — Self-Service BI Begins

Tableau's visual query paradigm empowered analysts without SQL expertise, dramatically expanding the number of people creating dashboards and thus the surface area for definitional drift.

2010s

Governed Self-Service & Data Catalogs

Enterprise data catalog tools like Alation and Collibra emerged alongside Tableau Server's certification features, signaling an industry consensus that documentation must live alongside the data, not in separate wikis.

2021+

Tableau Catalog & Metrics Layer

Tableau introduced Catalog (part of Data Management) and a Metrics layer, enabling organizations to define canonical metric definitions once and propagate them across all downstream workbooks.

The central question this lesson addresses is straightforward yet frequently underestimated: How do we ensure that every consumer of a Tableau workbook interprets each field and calculated metric in exactly the same way? Without rigorous documentation—data dictionaries, metric definitions, and explicit assumption statements—analytics environments devolve into competing truths, undermining the credibility of the entire platform.

SECTION 2

Core Principles & Definitions

Before diving into Tableau-specific implementation, it is essential to establish the foundational concepts that underpin robust data documentation. Three interrelated artifacts form the backbone of governance: the data dictionary, which catalogs fields and their properties; metric definitions, which specify how raw fields combine into business measures; and assumption documentation, which records the conditions and constraints under which the data and metrics remain valid. These three artifacts work in concert much like an API specification in software engineering: they define the contract between data producers and data consumers.

Data Dictionary

A structured catalog that describes each field (column) in a data source: its name, data type, allowable values, source system, business meaning, and any transformation logic applied before it reaches Tableau.

Metric Definition

A precise specification of a business measure: the formula (e.g., SUM, COUNTD, ratio), the grain at which it is valid, included/excluded segments, and the time window over which it is aggregated.

Assumption Documentation

An explicit record of preconditions—data freshness latency, NULL handling policy, currency conversion rates, fiscal calendar alignment—that must hold for published metrics to be accurate.

Lineage & Provenance

The traceability chain from a dashboard KPI back through calculated fields, data source extracts, ETL pipelines, and raw source systems. Tableau Catalog surfaces this automatically for governed data sources.

Certification & Trust Signals

Tableau Server/Cloud allows administrators to mark certain data sources and workbooks as 'certified,' visually signaling to consumers that the asset has been reviewed, documented, and approved for organizational use.

✦ KEY TAKEAWAY

Think of data documentation like the README.md and docstrings in a well-maintained software repository. Without them, a new developer can technically read the code, but they cannot confidently understand intent, edge cases, or expected behavior. A data dictionary is the README for your dataset, metric definitions are the function-level docstrings for each calculated field, and assumption documentation is the CHANGELOG that records what was known and what might break.

SECTION 3

Visual Explanation — The Documentation Ecosystem

The diagram illustrates how source systems feed into a data dictionary, which informs both metric definitions and assumption documentation. Tableau Catalog provides lineage and certification, and all artifacts converge to support trustworthy published dashboards.

The diagram above illustrates the layered architecture of documentation artifacts in a governed Tableau environment. At the top, source systems produce raw data whose fields are cataloged in the data dictionary. Those field-level descriptions feed into two parallel artifacts: metric definitions (which compose fields into business measures) and assumption documentation (which records the conditions under which those measures hold). Tableau Catalog automates lineage tracking and supports certification badges, and all layers converge to produce published dashboards that consumers can trust. Notice the analogy to a software build pipeline: source code (raw data) flows through compilation (transformation), is validated against tests (assumption checks), and finally deployed (published) with release notes (documentation).

SECTION 4

How It Works — Anatomy of a Data Dictionary & Metric Definition

Data Dictionary Structure

A data dictionary entry for a single field typically captures the following attributes: the field name as it appears in Tableau (which may differ from the source column name), the data type (string, integer, float, date, boolean), the domain (allowable values or ranges), the business definition in plain language, and the source lineage tracing back to the originating table or API endpoint. Additional optional attributes include NULL policy, update frequency, sensitivity classification (PII, PHI), and the name of the data steward responsible for the field.

Data dictionary entry for a revenue field

Attribute	Example Value	Purpose
`field_name`	`Order Revenue`	Human-readable name displayed in Tableau
`source_column`	`orders.total_amt`	Maps Tableau field back to the raw source
`data_type`	`FLOAT`	Prevents misinterpretation (e.g., ZIP code as integer)
`domain`	≥ 0.00; USD	Defines valid range and units
`business_definition`	Total amount charged to the customer after discounts, before tax and shipping	Eliminates ambiguity across teams
`null_policy`	NULLs indicate cancelled orders; excluded from revenue sums	Documents edge-case handling
`steward`	Finance Analytics Team	Identifies accountable owner for data quality

Metric Definition Structure

A metric definition goes beyond describing a single field; it specifies how one or more fields combine into a meaningful business measure. Formally, a metric definition includes the metric name, its formula (expressed in Tableau calculated field syntax or SQL), the grain (the level of detail at which the metric is valid—daily, per customer, per transaction), filters and segments (which records are included or excluded), and a time window (trailing 30 days, fiscal quarter, calendar year). This specification acts like a function signature in programming: it constrains the inputs and defines the expected output.

EXAMPLE METRIC FORMULA

Monthly Active Users (MAU) = COUNTD([User ID]) WHERE [Event Date] ∈ [month_start, month_end] AND [Event Type] ≠ 'bot'

COUNTD performs a distinct count; [User ID] is defined in the data dictionary; the grain is monthly; bot events are excluded per the assumption documentation.

SECTION 5

Detailed Breakdown — Types of Assumptions & Documentation Artifacts

This taxonomy shows how each top-level documentation artifact (data dictionary, metric definitions, assumptions) decomposes into constituent attributes, all of which map to concrete Tableau features like field descriptions, calculated field comments, and Catalog lineage.

Categories of Assumptions

Assumptions fall into several distinct categories, each of which should be explicitly documented. Data quality assumptions address freshness (e.g., the extract refreshes every 6 hours, so intra-day figures are stale), completeness (e.g., only 92% of transactions have a populated region field), and accuracy (e.g., self-reported survey data may contain measurement noise). Business logic assumptions cover decisions like fiscal calendar alignment (a fiscal year starting in February), currency conversion methodology (spot rate vs. average rate), and customer segmentation rules (enterprise customers defined as annual contract value ≥ $100,000). Technical assumptions capture implementation details such as join type choices (inner vs. left outer), deduplication logic, and the impact of Tableau's data densification on aggregations. Failing to document any of these can produce dashboards that are technically correct at the SQL level but semantically misleading to stakeholders.

Data Quality — Freshness SLA, NULL rates, known data gaps, deduplication method
Business Logic — Fiscal calendar, currency conversion, segmentation rules, exclusion criteria
Technical — Join types, extract vs. live connection behavior, data densification effects, row-level security filters
Temporal — Time zones, daylight savings handling, event timestamp vs. processing timestamp

SECTION 6

Worked Example — Documenting a "Churn Rate" Metric in Tableau

Suppose your analytics team has been asked to publish a dashboard showing monthly churn rate for a SaaS product. Multiple stakeholders have different intuitions about what "churn" means. The following worked example walks through the complete documentation process, from data dictionary entries through to a finalized metric definition with explicit assumptions.

Documenting the Monthly Churn Rate Metric

Step 1 — Identify Required Fields in the Data DictionaryBegin by identifying which raw fields the churn metric depends on. In this case, you need [Customer ID] (STRING, unique identifier per account), [Subscription Status] (STRING, domain: {'active', 'churned', 'paused', 'trial'}), and [Status Change Date] (DATE, the date the status transition occurred). Each field must have a complete data dictionary entry before the metric is built.

Three fields identified and added to the data dictionary with full metadata.

Step 2 — Define the Metric FormulaThe team agrees on the following definition: Monthly Churn Rate equals the count of distinct customers whose status changed to 'churned' during the month, divided by the count of distinct customers who were 'active' at the start of the month. In Tableau calculated field syntax, this is expressed as:

COUNTD(IF [Subscription Status] = 'churned' AND DATETRUNC('month', [Status Change Date]) = [Report Month] THEN [Customer ID] END) / COUNTD(IF [Active at Month Start] = TRUE THEN [Customer ID] END)

. This formula is recorded in the metric definition document along with its name, grain, and owner.

Metric formula: Churn Rate = Churned Customers in Month ÷ Active Customers at Month Start

Step 3 — Specify Grain and ScopeThe metric is valid at the monthly grain. It should not be aggregated to quarterly by simply averaging three monthly values (the correct approach is to recompute at the quarterly grain). The scope includes all customer segments except trial accounts, which are excluded because they have not yet converted to paid subscriptions.

Grain: monthly; Scope: all non-trial customers.

Step 4 — Document AssumptionsThree assumptions are recorded. First, the data extract refreshes nightly at 02:00 UTC, so the dashboard shows churn as of end-of-prior-day. Second, customers who pause and then resume within the same month are not counted as churned. Third, the denominator uses the snapshot of active customers on the first day of the month, not a running count, which means mid-month activations are excluded from the denominator for that period.

Three explicit assumptions documented: refresh latency, pause handling, denominator snapshot logic.

Step 5 — Publish and Certify in TableauThe data source is published to Tableau Server with the data dictionary entries added as field descriptions (right-click a field → Default Properties → Comment). The metric definition and assumptions are recorded in the data source's description field and in a companion Confluence page linked via the workbook's description URL. The data source is then certified by the Tableau Site Admin, giving it a green badge that signals to all users that this is the authoritative churn data source.

Certified data source published with embedded field descriptions and linked assumption documentation.

SECTION 7

Strengths, Limitations, and Common Pitfalls

Strengths, limitations, and mitigation strategies for data documentation

Strengths	Limitations	Mitigation Strategies
Eliminates definitional ambiguity across teams; everyone computes revenue identically	Documentation can become stale if not maintained alongside schema changes	Integrate documentation updates into your CI/CD or data pipeline change process
Accelerates onboarding—new analysts can self-serve without tribal knowledge	Overhead of creating and maintaining artifacts can slow initial development	Start with high-impact metrics first (top 10 KPIs); expand incrementally
Supports regulatory compliance and auditability (SOX, GDPR data lineage)	Tableau's built-in description fields have limited formatting and discoverability	Supplement with Tableau Catalog or an external data catalog tool (Alation, dbt docs)
Enables impact analysis—know which dashboards break if a field changes	Requires organizational buy-in; documentation is often deprioritized relative to features	Make documentation a definition-of-done criterion in your analytics workflow

✦ KEY TAKEAWAY

Documentation governance is analogous to maintaining unit tests in a software codebase. Tests do not write themselves, they require discipline to keep current, and they slow down initial development—but a mature test suite prevents far more costly failures in production. Similarly, a well-maintained data dictionary and set of metric definitions prevent costly misinterpretation in executive decision-making, which is the 'production environment' of analytics.

SECTION 8

Connection to Advanced Governance — Metrics Layer, Semantic Models, and Data Contracts

The documentation practices discussed in this lesson represent the foundational layer of data governance. In more advanced architectures, these concepts scale up into formalized constructs. The modern semantic layer (also called a metrics layer or headless BI layer) centralizes metric definitions in a single system—such as dbt's Semantic Layer or Tableau's own Metrics feature—so that every downstream tool (Tableau, Slack, spreadsheets) consumes the same calculation. Similarly, the emerging data contract paradigm formalizes assumptions as machine-readable schemas: data producers commit to delivering data that meets specified freshness, completeness, and schema constraints, and automated tests validate compliance before downstream consumers are affected.

Foundational vs. advanced governance implementations

Concept	This Lesson (Foundational)	Advanced Implementation
Field Documentation	Manually maintained data dictionary (spreadsheet or wiki)	Auto-generated catalog via Tableau Catalog, Alation, or dbt docs
Metric Definitions	Documented in workbook descriptions and calculated field comments	Centralized semantic layer enforcing one definition across all tools
Assumption Tracking	Human-readable notes in Confluence or workbook descriptions	Machine-readable data contracts with automated validation (e.g., Great Expectations, Soda)
Lineage	Manually documented source-to-dashboard mapping	Automated lineage via Tableau Catalog, OpenLineage, or Marquez

As your organization's data maturity increases, the manual documentation artifacts you create today evolve into inputs for automated governance systems. The conceptual understanding—knowing what to document and why—remains constant regardless of tooling. Whether you are writing a field description in Tableau Desktop or defining a metric in YAML for dbt, the underlying discipline is identical: specify the name, the formula, the grain, the scope, and the assumptions.

SECTION 9

Practice Problems

PROBLEM 1 — CONCEPTUAL

Explain, in your own words, the difference between a data dictionary and a metric definition. Why is it insufficient to have only one of these artifacts when governing a Tableau environment?

PROBLEM 2 — BASIC APPLICATION

You have a Tableau data source with a field called avg_session_duration. Write a complete data dictionary entry for this field, including at least five attributes (field name, source column, data type, domain, business definition, and null policy).

PROBLEM 3 — INTERMEDIATE

A marketing team and a finance team both report 'Customer Acquisition Cost' (CAC), but their numbers consistently differ by 15–20%. Describe a systematic process using data dictionaries and metric definitions to diagnose and resolve this discrepancy. What specific documentation artifacts would you examine or create?

PROBLEM 4 — APPLIED

You are the data governance lead at a mid-size company that has just migrated to Tableau Cloud. The CEO asks why the 'Monthly Revenue' figure on the executive dashboard differs from the number reported in the quarterly SEC filing. Outline how you would use Tableau Catalog's lineage features and your documentation artifacts to perform a root cause analysis. What assumptions would you check first?

PROBLEM 5 — CRITICAL THINKING

Some data engineering teams argue that documentation should be 'code' rather than prose—metric definitions in YAML, data contracts as JSON Schema, and documentation auto-generated from these machine-readable artifacts. Others argue that human-written prose descriptions are essential because they capture nuance and context that structured formats cannot. Critically evaluate both positions. Under what conditions would you recommend each approach, and how would you implement a hybrid strategy in a Tableau-centric organization?

SUMMARY

Lesson Summary

Effective data governance in Tableau begins with three foundational documentation artifacts. The data dictionary catalogs every field with its name, type, domain, business definition, and source lineage. Metric definitions specify how fields combine into business measures by recording the formula, grain, scope, and time window. Assumption documentation records the preconditions—data freshness, NULL handling, business logic decisions—under which metrics remain valid.

Within Tableau, these artifacts are implemented through field descriptions, calculated field comments, data source and workbook descriptions, and Tableau Catalog for automated lineage and certification. As organizations mature, these manual artifacts evolve into machine-readable semantic layers and data contracts, but the conceptual discipline of specifying what each field means, how metrics are computed, and what assumptions hold remains the enduring foundation of trustworthy analytics.