AI for documentation and data dictionaries

The model wrote fifty column definitions in four minutes. They sounded official: “customer_id uniquely identifies a customer across systems,” “revenue is total sales,” “active means the account is in good standing.” Nobody checked. Three months later Finance and Growth still argue about weekly revenue, and the catalog proudly displays the AI prose next to a table that means something else. Documentation speed without verification is how catalogs become museums of confident fiction.

This is Part 8 of Practical AI for analytics people. Part 7 covered privacy when pasting data into chat tools. Here we put AI to work on something analysts always under-invest in: data dictionaries and lightweight catalog cards. The rule is simple enough to print: draft, then verify. AI accelerates the blank page. Humans own meaning, grain, and the right to publish. Pair with stewardship catalogs: Data stewardship at work (especially Part 2 on truth maps), Data quality, and Data governance.

What you’ll learn

What a useful dictionary entry contains (and what fluff to skip)
A draft → human verify → publish flow you can run in under an hour
Prompt patterns that force structure and refuse hallucinated columns
A verification checklist with pass criteria before anything is “certified”
How to keep privacy habits from Part 7 while documenting real systems
Common mistakes, practice drills, and where dictionaries meet quality tests

What a data dictionary is for (analyst version)

A data dictionary answers practical questions: What does this table mean? What is one row? What does this column measure? Who owns it? What must I not use it for? It is not a novel about company history. It is not a dump of every raw landing table tagged “important.” It is a search entry for people who need to decide or build without a tribal elder on Slack.

Minimum fields that actually get maintained:

Field	Why it matters	Example
Object name	Exact qualified name	`analytics.certified.weekly_order_facts`
Purpose	One sentence decision use	Weekly net revenue for Finance packs
Grain	What one row means	One row per `order_id` × `week_end_date`
Key columns	Join and filter honesty	`order_id`, `customer_id`, `amount`, `status`
Definitions	Metric formulas in plain English	Net = paid amounts minus refunds
Owner / steward	Who answers and who maintains	Owner: Finance lead; steward: orders analyst
Freshness	When it is safe to trust	Monday 08:00 America/New_York
Sensitivity	Paste and access posture	No email; `customer_id` is strong key
Do not use for	Prevents wrong confidence	Not for real-time fraud; not incomplete current week as final
Last reviewed	Certification is a clock	2026-03-01 by orders steward

If your catalog tool has fifty optional fields, still fill these ten first. AI is excellent at drafting the prose around them. AI is terrible at knowing which of two “revenue” columns your CFO trusts.

The only flow that stays honest: draft, verify, publish

Treat AI documentation like a junior teammate who types fast and invents details when insecure. The workflow is a loop, not a one-shot publish button.

AI dictionary flow source draft human verify publish to catalog

Source: gather schema (names, types), a few synthetic or non-sensitive sample values, existing metric wiki links, and known do-not-use rules. Prefer information schema and dbt YAML over pasting prod rows (Part 7).
Draft: ask the model for structured cards per table and per critical column. Demand uncertainty markers for guesses.
Human verify: check grain, formulas, owners, sensitivity, and “do not use” against reality (SQL counts, owners, Finance language).
Publish: only after verify. Status experimental until a steward signs last_reviewed.
Revisit: when pipelines or metrics change, re-run draft on the diff and verify again. Dictionaries rot on the same schedule as code.

Rule of thumb: If you would not defend the definition in a meeting with Finance, it is not ready for the catalog, no matter how polished the AI wording.

Prompt patterns for dictionary drafts

Part 3’s prompt stack still applies: role, task, constraints, output shape, refuse inventing. For dictionaries, add explicit uncertainty and verification hooks.

# Dictionary draft prompt (schema + synthetic only)

You are helping draft a data dictionary card for analytics engineers.
Use ONLY the schema and notes I provide. Do not invent tables or columns.
If something is unclear, write UNCERTAIN: and a question instead of guessing.

## Object
name: analytics.certified.weekly_order_facts
columns:
  - order_id (string, not null)
  - week_end_date (date, not null)
  - customer_id (string, not null)
  - amount (numeric)
  - status (string: paid | refunded)
  - region (string)

## Notes from humans (authoritative when present)
- Grain intended: one row per order_id x week_end_date
- Net revenue for Finance packs uses paid minus refunds
- Do not use for real-time fraud
- Owner: finance_analytics_lead; steward: orders_domain_analyst
- No email or phone in this table

## Output format (YAML)
- purpose
- grain
- column_defs: list of {name, definition, sensitivity, conf: high|med|low}
- do_not_use_for: list
- open_questions: list
- last_reviewed: null  # human must set

Refuse any column not listed above.

Notice the output forces conf and open_questions. That is how you stop the model from sounding equally sure about order_id (obvious) and a subtle status rule (easy to get wrong).

Column-level prompt for messy names

Legacy warehouses love amt_1, flg_x, and cust_key2. AI can propose candidate meanings. You still prove them.

# Column meaning candidates (not truth)

For each column, propose up to 2 candidate definitions with confidence.
Require a verification SQL idea for each candidate (counts, distincts, joins).
Do not claim a candidate is correct.

columns: amt_1, flg_x, cust_key2
related tables (names only): orders, order_payments, customers
business words we use: gross merchandise value, net revenue, is_test_order

Then you run the verification SQL on a warehouse path that is allowed for your role. The model never sees the real result set if results are sensitive; you only feed back “candidate A failed: amt_1 includes tax” as a text note for the next draft.

The verify checklist (pass criteria)

Verification is not “read the AI text and nod.” It is a short suite of checks. Fail any critical row and the card stays experimental.

Dictionary verify checklist table of checks and pass criteria

Check	How	Pass criteria
Name exactness	Compare card to information_schema / dbt manifest	Every column on the card exists; no extras
Grain sentence	Say “one row means…” then test duplicates on keys	Primary key or uniqueness holds on sample window
Metric formula	Reconcile one week to a trusted report or prior notebook	Totals match within agreed tolerance
Status / enum values	`SELECT DISTINCT` on real data	Card lists real values; unknown values documented
Joins	Spot-check fan-out with counts before/after join	No silent row multiplication on documented joins
Sensitivity	Scan column list against PII ladder	Flags match; paste guidance correct
Owner / steward	Message the named humans	They accept the role (not a ghost name)
Do not use for	Ask one consumer what they almost misused it for	At least one concrete anti-use captured
Freshness claim	Compare max date / job success to SLO text	Card matches reality this week
Open questions	None left as fake certainty	UNCERTAIN items resolved or still listed as open

This is the dictionary twin of the AI SQL checklist: speed is allowed, shipping fiction is not.

Worked example: weekly_order_facts card

You feed the model the schema prompt above. It returns polished YAML. You verify:

-- Grain check: should be unique on order_id + week_end_date
SELECT order_id, week_end_date, COUNT(*) AS n
FROM analytics.certified.weekly_order_facts
WHERE week_end_date BETWEEN DATE '2026-02-01' AND DATE '2026-02-28'
GROUP BY 1, 2
HAVING COUNT(*) > 1
LIMIT 20;

-- Enum check
SELECT status, COUNT(*) AS n
FROM analytics.certified.weekly_order_facts
WHERE week_end_date = DATE '2026-02-28'
GROUP BY 1
ORDER BY n DESC;

-- Finance reconcile sketch (toy window)
SELECT
  ROUND(SUM(CASE WHEN status = 'paid' THEN amount
                 WHEN status = 'refunded' THEN amount
                 ELSE 0 END), 2) AS net_amount
FROM analytics.certified.weekly_order_facts
WHERE week_end_date = DATE '2026-02-28';

Suppose the grain query returns zero duplicate pairs, statuses match the card, and net_amount matches Finance’s known week within $0.01. Owners confirm. You set last_reviewed and publish. Suppose instead net_amount is double Finance’s number. You do not “edit the catalog to sound better.” You open an investigation: maybe refunds are stored as positive amounts with a flag, and the AI formula was wrong. Fix the definition (or the model), re-verify, then publish. Catalog prose is a downstream artifact of truth, not the source of it.

Example published card (after verify)

object: analytics.certified.weekly_order_facts
purpose: "Weekly net revenue inputs for Finance packs and Growth review."
grain: "One row per order_id x week_end_date."
owner: finance_analytics_lead
steward: orders_domain_analyst
columns:
  order_id: "Checkout order identifier; stable join key to order system of record."
  week_end_date: "Week ending Sunday in America/New_York; not transaction timestamp."
  customer_id: "Customer account key; strong identifier; not an email."
  amount: "Signed order amount in USD; refunds negative when status=refunded."
  status: "paid | refunded only in certified table; other statuses excluded upstream."
  region: "Shipping region bucket used by Finance packs (east/west/central)."
definitions:
  weekly_net_revenue: "Sum of amount for the week; refunds already signed negative."
sensitivity:
  pii_direct: false
  notes: "customer_id is a strong account key; treat as personal in joins to CRM."
do_not_use_for:
  - real_time_fraud
  - incomplete_current_week_as_final
  - customer_email_outreach (no email here; do not join casually for marketing)
freshness_slo: "Monday 08:00 America/New_York"
last_reviewed: "2026-03-01"
reviewed_by: orders_domain_analyst
draft_tool: "enterprise AI draft v0; human verified"
status: certified

The draft_tool line is optional honesty. It reminds future readers that AI helped type, humans signed. That cultural signal matters more than the YAML flavor.

Where AI helps most (and where it wastes time)

Task	AI fit	Human must own
Turning schema into first-pass prose	High	Exact names and types as source
Suggesting column meanings from messy names	Medium	Verification SQL and owner sign-off
Writing consumer-facing plain English	High	Business vocabulary match
Choosing system of record vs curated truth	Low	Truth map and org politics
Declaring certified status	None	Steward + checks + clock
Bulk documenting every raw table in month one	Tempting, harmful	Scope to certified assets first

Stewardship Part 2 warned against catalog theater: everything tagged, nothing trusted. AI makes theater cheaper. Resist. Document the few objects that drive decisions. Use AI to make those few excellent.

Privacy while documenting

Dictionary work still collides with Part 7:

Prefer information schema, dbt docs, and synthetic examples over real customer rows in prompts.
If you must show value distributions, use aggregates or fake samples that preserve shape.
Mark sensitivity on the card so future pastes and access reviews start from truth.
Do not paste credentials that appear in warehouse connection notes “for context.”

Documenting personal data fields is allowed and necessary. Shipping those fields into an unapproved chat tool to write the documentation is not the same activity.

Tie dictionaries to quality and metrics

A definition without a test is a hope. When you certify a card:

Link the metric wiki or metrics-series style spec for any KPI language.
Point at the quality suite or scorecard that protects grain and null rules.
If freshness fails repeatedly, revoke certified status in the same week you notice (stewardship lesson: badges without clocks teach cynicism).

AI can draft the test descriptions too. Same rule: draft, then verify by running them.

Common mistakes

Mistake	Why it hurts	Better habit
Publish AI text as certified	Fiction with a badge	last_reviewed only after checks
Document every table in week one	Empty fields, cynicism	Certified decision assets first
No grain sentence	Every total becomes ambiguous	Force “one row means…”
Invented columns in the draft	Readers chase ghosts	Schema-only prompts; refuse extras
Skipping owner confirmation	Orphan definitions	Named human accepts role
Pasting prod samples to “improve prose”	Privacy risk without quality gain	Synthetic shape samples
Never revisiting after pipeline changes	Silent drift	Re-verify on schema or metric change

How to practice this week

Pick one certified (or should-be-certified) table you use weekly.
Export column names and types only. Draft a card with AI using the structured prompt.
Run the verify checklist. Log every UNCERTAIN you resolve.
Publish or update the catalog entry with last_reviewed and your name.
Add one do-not-use rule that would have saved a real past argument.
Schedule a 90-day revisit on the calendar. Dictionaries without clocks die.

Quick recap

Dictionaries exist to answer meaning, grain, ownership, and misuse quickly.
AI is a drafting partner: source → draft → human verify → publish.
Force structure, uncertainty markers, and refuse invented columns.
Verify with SQL, owners, sensitivity, and reconcile checks before certified status.
Keep Part 7 paste hygiene while documenting; link quality tests and metric specs.
Scope beats theater: few excellent cards beat hundreds of empty ones.

What’s next

Part 9 closes the series with a personal AI ops checklist: expand the AI-SQL habits to charts, Python, and stakeholder email, add a weekly hygiene pass, and recap Parts 1 through 9 so you leave with a Monday system, not only ideas.

Sources

Research and further reading used for this article:

NIST AI Risk Management Framework (map and measure thinking that pairs with human verification of AI outputs)
NIST AI RMF 1.0 publication (core functions for managing AI risk in organizations)
OWASP Top 10 for LLM Applications (overreliance and sensitive information disclosure risks when trusting generated text)
ISO/IEC 11179-1:2023 Metadata registries (formal metadata registry concepts many enterprises map dictionaries toward; heavy, useful for program language)
W3C: Data Catalog Vocabulary (DCAT) 3 (interoperable catalog concepts for datasets and distributions)
IAPP: Glossary of privacy terms (sensitivity language when dictionary fields describe personal data)
NIST Privacy Framework (privacy risk outcomes that documentation and data inventories support)
Analytics Made Simple: How to Check AI-Written SQL
Analytics Made Simple: Data governance
Analytics Made Simple: Data stewardship at work

Keep going

Same lessons in your feed

Short diagrams and hooks on Instagram, X, and Facebook.

@analyticsmadesimple Follow @AnalyticsSimply Follow Analytics Made Simple Follow