Chevron Left

See all Community Stories

How to document data

December 12, 2024

Contributed by

Rick Radewagen

Snowboard Software

photo of Rick Radewagen

Rick Radewagen is a co-founder of Snowboard, a company that helps teams to find, understand and trust their data. Before that he spent many years pumping and crunching data in various organizations. You can find Rick on LinkedIn.

The goal of data documentation is simple: help users find the right data, understand how to use it, and trust that it’s accurate.

But that doesn’t mean you need to document everything. In many cases, well-modeled data is already self-explanatory.

Just like “good code documents itself,” good data modeling does a lot of the heavy lifting. If your tables and columns have expressive, consistent names, they’ll be easier to understand.

A database called ‘dbo‘ is vague and confusing. But ‘sales_prod‘ or ‘finance_reporting‘ gives users immediate context—especially if there’s also a ‘sales_dev‘ or ‘marketing_staging‘ around.

So, documenting data starts with naming things well—but it doesn’t end there.

Use Your database hierarchy to document data top-down

Take advantage of your data system’s structure to create top-down documentation. That means organizing your documentation starting from:

  • System
  • Database
  • Schema
  • Table
  • Column

5 steps to document data correctly

This hierarchy helps users see the big picture, explore related data, and understand how different parts connect. When you document data this way, people can more easily navigate your data landscape without needing to ask around.

What to focus On when documenting your data

You don’t need to go overboard. Here’s how to document data effectively without getting overwhelmed:

✅ Document the top 3 levels completely: system, database, and schema

✅ Focus on the top 10% most-used tables in your stack. If you’re using Metabase, check usage analytics to prioritize based on what people actually explore and query.

✅ Set a rule: new tables, views, or models must include basic documentation at creation time

💡 Pro tip: If a column isn’t worth documenting, it probably doesn’t belong in the table.

For core reporting tables and widely used data products, be rigorous. These should include detailed column-level documentation and clear descriptions of what each field means.

Naming conventions and glossaries matter

Sometimes the hardest part of documenting data is choosing the right words. Is it a customer, account, company, user, or site? Are acronyms like LTV, ARR, or CAC clear to everyone?

To reduce confusion, your data documentation tool should support a glossary—a centralized place to define key business terms. Then, you can reference those definitions consistently across your documentation.

Quick tips for better data documentation

  • Use expressive and consistent names;
  • Document top-down and most used;
  • One sentence is usually enough;
  • Make documentation part of the development process;
  • Use #definitions in a business glossary;

Contributed by

Rick Radewagen

Snowboard Software

photo of Rick Radewagen

Rick Radewagen is a co-founder of Snowboard, a company that helps teams to find, understand and trust their data. Before that he spent many years pumping and crunching data in various organizations. You can find Rick on LinkedIn.

You might also like

Anticipating the next click

Ukrit Wattanavaekin

Metabase

Why you should invest in a data catalog

Ali Baghshomali

Mentat Analytics

You might also like

Anticipating the next click

Ukrit Wattanavaekin

Metabase

Why you should invest in a data catalog

Ali Baghshomali

Mentat Analytics