Josh Moore

The state of dbt documentation in 2026: why nobody reads your docs

Six years, 43 comments, still open. A look at what analytics engineers have been asking dbt-docs for, and what an alternative looks like.

Your dbt docs are out of date. You know it. Your team knows it.

Someone pinged you in Slack last week asking where the revenue field on fct_orders comes from. You opened the docs site, searched, scrolled past 400 models on a single page, and gave up. You traced the model yourself. It took ten minutes. You promised yourself you’d update the description. You didn’t.

This is the quiet pain of every analytics engineering team I’ve worked with. Documentation is an agreed-upon good that nobody uses. The reason isn’t laziness or a culture problem. The tool everyone reaches for, dbt docs serve, was never built to be the thing.

I wanted to know if my experience was specific to my last few teams or something broader. So I spent an afternoon last week reading every open issue on the dbt-labs/dbt-docs GitHub repo. The pattern was striking.

What analytics engineers have been asking for, going back six years

The single most-commented open issue in dbt-labs/dbt-docs is #84, Create ERD from relationships in schema.yml files. Forty-three comments. Opened in April 2020. Still open in May 2026. A schema diagram showing how your models relate to each other, which most people would call table stakes.

Then there’s #50, White-labeling dbt docs. Fifteen comments. Opened September 2019. Teams want to put their company’s branding on the docs they share with internal stakeholders. Still open.

Two from this January, both about visibility into model state:

None of these are exotic. A schema diagram. Branding. A freshness signal. Offline metadata. These are the basics of what data documentation should have, and every one of them has been a thoughtful request from a real analytics engineer with a real use case. The dbt docs serve experience has barely moved against any of them.

This isn’t a critique of the dbt-labs team. They’re shipping the rest of the platform at a pace most data tooling can’t match. dbt docs serve does what it was built to do: render a reference view of your project. It was never meant to be the documentation tool for a 50-person data org. That’s on us, the users, to build or buy.

Why your team doesn’t open the docs

The default dbt docs serve experience is a single-page static site that lists every model on one page. You get documentation in the dbt sense: every model named, every column listed, descriptions if someone wrote them. What you don’t get is a documentation experience.

Search that finds things. The built-in search is keyword-based and shallow. On a 500-model project, finding a specific column takes more time than asking a teammate.

Column-level lineage. You can see which models feed into which models. You can’t answer the question that matters: “what happens upstream if I change the order_status enum on dim_orders?” The graph stops at the model boundary.

Model health signals. Every model in the docs looks the same. You can’t tell which models have tests, which are documented, or which haven’t been edited in eighteen months. The docs site treats a freshly-shipped model and a stale 2022 prototype identically.

A way to share with non-technical teammates. dbt docs serve runs a local server on localhost:8080. To share with a stakeholder you’re either screen-sharing your laptop, hosting the static files yourself, or, somehow, asking them to install dbt and run a CLI command.

Integration with where your team already works. Your analysts live in Slack. Your stakeholders live in email. Your docs live at localhost:8080.

The result is what you’d expect: nobody opens the docs. The tool the team uses is the senior analytics engineer who’s been there longest and remembers the lineage in their head.

The senior engineer becomes the documentation

When the documentation tool doesn’t work, somebody fills the gap. That somebody is usually one specific person on your team. The one who built the warehouse. The one who remembers why stg_payments has a deduplication step. The one who can trace revenue back to its source in fifteen seconds.

Slack pings them. Stakeholder questions route to them. New hires shadow them. They spend ten minutes tracing models other people wrote because it’s faster than searching the docs. They promise themselves every Monday they’ll update the descriptions this sprint. They don’t.

This is a failure mode that compounds. The more people ping that person, the less time they have to improve the docs. The less the docs improve, the more people ping. Your team’s collective understanding of the data model is bottlenecked on one person’s memory and availability.

Most analytics engineering teams I’ve worked with have at least one person in this position. Some have two. Most have one and a half: a primary holder of institutional knowledge, and a junior partner trying to absorb it.

What I’ve been building

For the past few months, I’ve been building an alternative to dbt docs serve. It’s called Docglow, it’s open source, and it takes the same manifest.json and catalog.json your project already produces and turns them into a documentation site I’d want to open.

Three things it does:

pip install docglow
docglow generate --project-dir ./my_dbt_project
docglow serve

Almost 3,000 data practitioners installed Docglow over the last month from PyPI. I’ve never run an ad. The word gets around because people find dbt docs serve insufficient and go looking for an alternative.

It’s not perfect. The gaps:

What’s coming

In a few weeks I’m launching Docglow Cloud, the hosted version. It’ll add three things the OSS tool doesn’t:

If your team has these problems

If any of this matches your team (stale docs, senior engineer as documentation oracle, 500-model single-page-static-site experience), try the open-source tool. It’s a single pip install away, and the OSS will stay free.

If it fills the gap, great. If it doesn’t, open an issue and tell me what’s missing. I read every one of them.

The dbt-docs issues I linked above suggest that whatever’s frustrating you about dbt docs serve is probably frustrating a lot of other teams too. After six years and 43 comments on the most-requested issue, it’s reasonable to stop waiting.