Solo DevRel documentation: A conversation with DuckDB’s Gábor Szárnyas
DuckDB’s Gábor Szárnyas explains how a solo DevRel maintains SQL docs at scale, achieves feature parity, and prepares documentation for the LLM era.
Gábor Szárnyás works in developer relations at DuckDB Labs, where he spends about half his time on technical writing for the documentation and blog. With a background in academia — including a master’s in databases, a PhD, and two postdocs — he brings a researcher’s mindset to documentation. After contributing to DuckDB’s docs as a user, he joined the company 19 months ago and immediately undertook a major documentation overhaul.
We sat down to discuss how DuckDB approaches documentation for a complex database product, the challenge of keeping docs in sync with rapid development, and why he believes comprehensive documentation actually saves development time.
To start, can you tell me a little about your background and how you came to work on documentation at DuckDB?
I worked in academia for a long time. I was really dead set on becoming a professor, so I jumped through all the hoops for that — a master’s in databases and distributed queries, a PhD, a postdoc, another postdoc. Ultimately, that career track didn’t work out for me, but I knew I wanted to do a lot of writing, I liked doing presentations, and I still wanted to teach people. Obviously, developer relations for DuckDB, which is quite a successful project, is a good platform to do all these. And this kind of worked out.
One of the reasons I came here is because I was already a contributor to the documentation. Prior to joining DuckDB, I was using it, found some issues, sent some pull requests, and I already quite liked the process. Now I’m here as a developer relations person, and I would say about half of my time is spent on technical writing — the documentation and the blog. A good 80% of what’s in the docs, what gets in there as new content, is written by me.
And when you got there, you did a major overhaul of the existing documentation. What was it like before and what did you want to change?
On the technical side, I really strived to achieve a point where everything that’s in DuckDB is at least mentioned in the documentation. To jump back one step from that, it’s also something to mention that we don’t really have a strict process. I know some companies say you cannot merge a feature until you do documentation on it. We don’t have such a process. DuckDB can get ahead of the documentation and have features that are undocumented. So that was one thing I started to fix when I got here, so that we don’t have this mismatch between the docs and the codebase.
“We have a lot of discussions internally where people want to change something, and they say ‘this will not be a breaking change.’ And then I point them to the documentation and say, ‘Well, we promised this behavior in the docs, so if you change it, it will be a breaking change.’ Having everything written down helps us make these decisions.”
There were also a lot of stylistic changes in how the documentation is written — grammar-wise, formatting-wise, the conventions used in the SQL examples. I tried to remind myself that, because this project is so popular, people will learn SQL from it. I spend a great deal of time just making sure that SQL is actually nice, and they actually learn a SQL convention that is pretty common and also nice-looking. I go through a lot of hoops in making sure that the syntax highlighter is nice, that the placeholders that people need to fill in are obviously signed, things like that.
Sounds like you’re focusing on nice details! And how important do you think the documentation is for your users?
I do think it’s very important. It’s a complex question. One aspect is that DuckDB has chosen to do a Postgres-compatible SQL dialect, and initially, when the documentation was in a more rough, raw shape, I always told people, “As a fallback, you can always visit the Postgres documentation and read that as a reference”. But it turns out this is not very practical.
So a big reason the docs are important is that it provides people with a single reference. They can just go to one place and they will know what DuckDB supports. They don’t need to go on an Easter egg hunt and check multiple places — is this a Postgres thing, is this a DuckDB extension of Postgres, or is this a DuckDB-specific thing?
The docs also serve as the single source of truth. We have a lot of discussions internally where people want to change something, and they say “this will not be a breaking change” or “this is fully backwards compatible”. And then I point them to the documentation and say, “Well, we promised this behavior in the docs, so if you change it, it will be a breaking change”. Having everything written down helps us make these decisions and maintain consistency.
Interesting — so your docs influence product decisions too! And how do you balance documenting features that come from the core team versus community contributions?
DuckDB is open source, but the governance is done by the DuckDB Labs company. We try to keep the software lean and only merge features that align with this core vision that the company has. That also implies that most of the features that arrive, I already know about — they’ve been around in meetings and discussions. So there’s little disagreement or things to balance there.
The user-contributed things are in the community extensions repository, and that’s kind of auto-generated by their descriptor files. We have an issue tracking system where people who develop features just tag them with “needs documentation” in the DuckDB repo, and it gets into my to-do list in the issues record of the documentation repo.
What are some of the challenges you face maintaining the documentation?
One challenge is when people implement something quickly and it works, but documenting it properly would reveal that the behavior is not entirely consistent or well-thought-through. Sometimes I get pushback when I ask questions like “how does this interact with that feature?” or “what happens in this edge case?” And the answer might be “we haven't thought about that.”
So the documentation process actually helps improve the product, because it forces us to think through these interactions and edge cases. But that means documentation takes time — not just writing time, but thinking time and sometimes implementation time to fix inconsistencies that the documentation process reveals.
That’s interesting — so documentation actually catches design issues?
Exactly. I always tell people that writing documentation is not just about explaining what exists, it’s about making sure what exists actually makes sense. When you try to explain something clearly and you can’t, that's often a sign that the thing itself isn’t clear enough.
And how do you think about metrics for documentation success?
We don’t have elaborate analytics set up. I occasionally look at page view statistics and that kind of stuff, but I haven't invested the time to set up something more sophisticated. Part of it is that DuckDB documentation serves multiple purposes — it’s a reference, it’s a tutorial, it’s sometimes the first place people learn SQL. So measuring “success” is complicated.
What I do pay attention to is feedback. We have buttons where people can report issues with the docs. Though I’ll be honest — we get some good reports, but we also get a lot of low-quality reports, and maybe even questions, and sometimes meaningless ones. It may actually be good to increase the barrier of entry, because if someone really wants to report an error and they know what they’re doing, they will do the extra three clicks. But if you just give people a button they can hit with a hammer and say “this is bad”, then they will do that.
So making it too easy to give feedback can actually create noise?
Yeah, I’ve started labeling those differently now. I added a label and I just, in my head, deprioritize it a bit. One thing I’ve observed recently is that there are quite a few people who just start writing essays about issues. They start to think through the semantics of things, and it’s not obviously a very valid thing. Then I’m left with three screens of text and not many actionable results. But that’s kind of part of open source, so it’s not a huge issue. Just sometimes I feel like that same user could have made a pull request and been done with it in the same amount of time.
Thinking more broadly, what do you see as best practices for database documentation specifically?
For databases, you need to be very precise about what’s supported and what isn’t. People need to know exactly what SQL syntax works, what functions exist, what the behavior is in edge cases. Vagueness is really problematic in database documentation.
I also think examples are crucial. SQL can be abstract, so showing concrete examples of how to use features helps people understand both the syntax and the use cases. And those examples need to be correct and tested — there’s nothing worse than documentation with examples that don’t actually work.
Any final thoughts on documentation for open source database projects?
I think comprehensive documentation is actually a competitive advantage. When someone is evaluating databases, good documentation makes DuckDB easier to try out, easier to understand, easier to adopt. And it reduces the support burden — if people can find answers in the docs, they don’t need to ask on Discord or GitHub.
It takes time to write good documentation, but I genuinely believe it saves time in the long run. And it makes the product itself better by forcing us to think through design decisions carefully.
This interview was published on 12 November 2025, and conducted as part of research for the 2025 State of Docs report.