Coming next: The Second Factory →

Back to Library
Data Foundations⚠️ Pitfall

Database Hieroglyphics (When Nobody Can Read Your Schema)

The Problem

Walking into a data warehouse and seeing table names like "cst_prf_x_loc_dim" is like reading ancient hieroglyphics without a Rosetta Stone. Nobody knows what it means. New analysts spend weeks deciphering the cryptic abbreviations. "sls_txn_f47"? Is that sales transactions fact table 47? Or sales tax new framework 47? Who knows? The team that built it left years ago. Now you're stuck with a metadata mess that requires a 200-page glossary just to understand what data you have. It's expensive, slow, and dumb.

The Principle

BAN ABBREVIATIONS ENTIRELY: Name everything like you're explaining it to your grandmother—clear, complete, obvious. "customer_profile_crosswalk_location_dimension" beats "cst_prf_x_loc_dim" every single time. Yes, it's longer. Yes, it takes more characters. But you know what? Developers onboard faster. AI tools actually work. Analysts build models without asking "what does this column mean?" seventeen times. The best documentation is code that doesn't need documentation. When your schema is self-explanatory, you stop wasting time on glossaries, metadata tools, and tribal knowledge. You start shipping value. Make it stupidly simple. If a new hire can't guess what a table contains from its name, you failed. Think manufacturing: you wouldn't label raw materials with cryptic codes and expect workers to be productive. Same here. Clarity is speed.

🎯

3 Steps to Take Action

  1. 1

    Ban Abbreviations Starting Today: New tables/columns get full names. "customer_profile" not "cst_prf." Make it a code review requirement. No exceptions.

  2. 2

    Rename Top 20 Tables: Pick your 20 most-used tables with cryptic names. Rename them during next migration. Document before/after. Train team on new names.

  3. 3

    Build a Naming Convention Guide: Document the standard: table_name format, column_name format, examples. Make it a 1-pager. Post it where everyone can see it.

In Practice

A Dutch architect joined a Fortune 100 retail company and was horrified by the schema. "cst_prf_x_loc_dim"? "sls_txn_f47"? "inv_adj_tmp_stg"? He couldn't make sense of it. Forced one rule on the team: zero abbreviations going forward. Everything gets renamed during the next migration. Six months later: "cst_prf_x_loc_dim" became "customer_profile_crosswalk_location_dimension". "sls_txn_f47" became "sales_transactions_fact". "inv_adj_tmp_stg" became "inventory_adjustments_temporary_staging". New developers onboarded in 2 weeks instead of 6 months. But here's the shock: AI velocity tripled. GPT-4 could read the schema and write accurate queries on the first try. Analysts built models without Slack messages asking "what does this mean?" The team that resisted ("it's too long!") eventually admitted defeat. Simple names compounded value across everything. One rule changed everything.

More on Data Foundations

From the book

In the book, a new hire takes six months to become useful, mostly because of table names nobody can read. And there are five definitions of an active seller.

This card is one of 57 drawn from The Auction Block by Brian Cariveau — the story of an analytics leader with 90 days to fix what the cards describe.

Each leadership pattern falls into a few pitfalls most often. Find your pattern.The Analytics Leadership Mirror: free, 5 minutes, no account