Open source documentation at scale: A conversation with dbt Labs’ Mirna Wong and Matt Shaver

Mirna Wong and Matt Shaver are Senior Technical Writers at dbt Labs, both bringing backgrounds in support to their documentation work. Mirna started at dbt in support before transitioning to technical writing — a career she didn’t know existed until her manager introduced the role.

Matt came from IBM and earlier support roles, becoming a product manager of documentation before joining dbt Labs. Together, they help maintain a developer hub that serves everyone from seasoned practitioners to beginners exploring the dbt ecosystem.

We sat down to discuss how dbt approaches documentation as an open-source project, the challenges of measuring documentation’s impact on product adoption, and how they think about serving an increasingly diverse user base.

First, can you tell me about your documentation structure today and maybe what you think you do a little differently from other doc sites?

One of the things that I find really exciting and hopefully unique is that a lot of our users are very much committed and in tune to our platform. And with that comes contributions.

Our docs are open source, which is awesome. I personally love it. I think the team really likes that too, because we’re able to engage in very personal ways with the community — not just reviewing their PRs and all that, which is always great, but even when they have feedback to improve our docs.

We have some very passionate developers who have particular feedback. We’re able to collaborate with them and kind of bring it full circle by having them contribute or open up a PR to address the feedback that they had, because we’ve worked together with it. I find that quite helpful and pretty special. It keeps us in tune with them.

And Matt, you mentioned the community aspect is different from previous experiences?

Matt Shaver: Yeah, I appreciate the kind of community that we’ve built here. Previous products I’ve worked on, the way that you would interact with folks about product feedback or docs feedback was through forums, which are very impersonal. You have moderators who go over things.

Here, since we’re open source, they can interact directly with us. And it’s not just us as the docs team — we have folks who open up docs requests and product management sees them, and they’re involved with that as well, along with developer community and things like that. So it’s very open source, very welcoming.

How do you measure the importance and effect of documentation for your users?

Mirna: It’s ever-evolving. We’re always trying to get better metrics. We use tools to gather qualitative feedback from users on how they think about the docs. And then we have the standard page views, engagement sessions, referrals, and search data.

We’re also trying to see if they’re actually coming from the cloud, our actual SaaS software, to help us see their journey. We try to track conversions — how many people who read the docs have signed up to our cloud software.

We also measure our GitHub metrics — how many PRs have been opened that month, how many are new contributors, how many issues are being opened and closed, just to get the health of the repository.

That’s a lot of different metrics. Do you work with other teams to get feedback as well?

Matt: We work a lot with other teams to get that sort of feedback. A good example is onboarding. We have an incredibly complex process, and it’s not going to be solved by a wizard — it’s just too complex. So the docs play an important role with that. We integrate with support, with learning teams, and with onboarding teams to make sure that our docs and everything work together.

Folks that use our docs aren’t always the most excited to fill out feedback forms, so we don’t get everything we need that way. But we get feedback through other teams. “I was onboarding and everything was going great and I hit a brick wall in the docs,” or, “this doc didn’t have information that I needed”. So integrating with those teams is extremely important to us to get feedback that otherwise might not make it to our desks.

You mentioned trying to measure whether people can successfully “do the thing” after reading docs. How do you approach that?

Mirna: Something we’re experimenting on right now is comparing a particular feature’s adoption rate, then trying to see how the docs play into that adoption. It’s not easy because there’s a lot of variables. Not everyone that views the docs can — or wants to — use the feature.

So we’re trying to see how viewing the docs for particular features links to the adoption of that feature — whether that’s in our open source tool, dbt Core, or our cloud SaaS offering, dbt Cloud. But it’s experimental right now because it’s a bit tricky.

And you have tools that help you understand user behavior on the pages themselves?

Matt: We have tools in place that can tell us if a person rage quits a page, or if they enter and exit real quickly, how far down they’re making it on the page, how long they linger in particular sections and things like that. So we can monitor the pages themselves and make sure that the journey is going smoothly for them as they’re learning about these features.

What would you like to measure better, or what are the things you don’t really know how to measure today that you think would be worthwhile?

Mirna: That’s a good question. Something we worked on in the past as a team was user research, which was great. I think that’s something we want to continue to expand on, particularly as our documentation grows. Sometimes when docs grow, you need to think about different personas that read your docs. So that’s something we want to continue to expand on and think about — personas and making sure that we have the docs arranged for the right users.

I think something that would be very helpful for us is measuring our information architecture. Because as it expands, we want to make sure that the IA meets the needs of the growing user and growing products as well.

Matt, you mentioned information architecture is a challenge?

Matt: Yeah, definitely. We don’t know what we don’t know. We get a lot of really positive feedback on our docs, but a lot of times people who have complaints just don’t bother to complain out loud.

And even for folks who have positive feedback, it’s like, “I found this page and this was extremely helpful and this helped me do exactly what I needed to do,” but we don’t know what their journey was like to find that page. Could they have found it sooner? Were they hitting any frustrations along the way? We’d like to work backwards through their journey.

How does the process work for keeping docs up to date or documenting new features?

Matt: We get a lot of it directly from product. We interact with product management directly on that. New features are always going to be number one — that’s just the way it is, we need to get the new features out the door. But as far as everything else, like catching up on backlog or enhancing existing pages, we have a prioritization system as a team.

And Mirna, how does that relationship with product teams work day-to-day?

Mirna: I think we have a pretty solid relationship with the product and engineering teams. Relationships are obviously very important, so we have great relationships with our respective PMs.

That helps us because with the PMs, we definitely focus on new features or updating features, but for existing things where our customer-facing teams are talking to users every day, we have a great feedback loop. That’s how we address those small paper cut things to make sure that our docs are as updated as possible.

Matt, you mentioned you’ve worked at places where the docs team finds out about features at the last minute. What makes it work better here?

Matt: I’ve definitely worked in organizations on docs where you don’t find out about the feature until it’s ready to go! They’re like, “Hey, we finished building this, we’re shipping it in three days, I need you to create documentation.”

Our team is tied in very early in the process, from ideation through creation. We are aware and we get information before most of the rest of the organization does. And so it’s been a huge boost to us.

What do you attribute that to?

Mirna: Well, we’re part of the EPD umbrella — engineering, product, design. Documentation is a part of that. I think that is very helpful. We do our best to meet with the product team regularly.

There’s a culture of transparency behind it, but also — our manager really believes in product and docs, and expresses that to leadership. Engineering management, engineering vice president, even going up to some of the C-levels, they understand that docs play a huge role. And if docs falter then a lot of other blocks will fall too. So they treat us with the kind of respect that you would hope a docs team would get.

How do you think about the future of documentation, particularly with AI?

Mirna: I think as AI evolves and gets smarter, I do view it as a helpful tool. I think there might be some organizations that rely on it maybe more so than they should. I always think — and this applies to engineering as well — the human in the loop is essential for many reasons. I think AI and technical writers can complement each other if done the right way, if executed the right way, and if both are respected, particularly tech writers.

I can see tech writing continuing to be very important in reviewing and making sure you’re tuned in to user journeys and stuff. That will be very essential because as powerful as AI is and will be, I think you still need that human in the loop element because of hallucination, outages, whatever. So I can see a world where they can complement each other, and I hope it’s that.

Matt, what are you thinking about for the future?

Matt: For me, it’s largely thinking of the international audience — i18n and how can we get to that step? How can we make sure that we’re breaking beyond the bounds of just the English language so that we can serve a larger, broader community?

In addition to that, how can we balance open source docs-as-code with some more flexibility? If you’ve worked in Markdown, you know that Markdown has limitations. How can we balance the limitation of docs-as-code with a more pleasant user experience so that as we grow, as we start targeting audiences who are less technical, we can make our docs as welcoming as possible to them?

When you say audiences who are less technical — is that people you want contributing to your docs or just reading them?

Matt: Right now we’re primarily focused on analytics engineers, which is a higher tier of analysts, but we want to go after the data analysts. We want to go after folks who are less technical, who know SQL but not Python, who maybe only know a couple of SQL commands to get their job done but are suddenly being thrust into dbt.

How can we make this a welcoming experience for them? And how can we make the docs as easy to interact with as possible as they go through probably a pretty frustrating journey to learn something new?

And how do you think about targeting different personas in your docs?

Matt: Guides. Guides that are targeted to particular personas, walk-throughs that look at step-by-step end-to-end processes targeting particular personas.

This interview was published on 29 August 2025, and conducted as part of research for the 2025 State of Docs report.