4 min read
Good docs are how developers work with a product, from first look to daily use. That’s been true for a long time, and it’s becoming more true as developers increasingly hand that work to agents on their behalf.
During the last quarter, we’ve been migrating docs.kosli.com from a static Hugo site to Mintlify, and now it’s finally live.
Early reactions from our customers: “A marked improvement over the old docs in layout and usability.” “Looking sharp!”
Why we moved
The honest reason isn’t the tooling. It’s that developers increasingly won’t read docs. They’ll ask an agent, or they’ll connect their tools directly and expect things to just work.
Hugo served us well, but it was built for a world where documentation was something only humans read. That world is changing fast. A developer evaluating Kosli today is just as likely to point an agent at our docs as to scroll through them, and the site needed to meet them there.
Built for how developers actually work
Mintlify’s built with that reality in mind. Ask the docs directly. Or use the MCP server and bring Kosli straight into your IDE, your CI setup, wherever you’re actually working. We also now serve a skill.md endpoint that agents can load to understand how to work with Kosli without any manual setup. The intent is to make onboarding significantly faster, whether you’re a human or an agent.
An API you can actually try
Our API reference used to be a specification you read, then a Swagger link you clicked, then a separate tab you figured out on your own. Now it’s a playground embedded directly in the docs. You can hit endpoints, see real responses, and work out the shape of what you need without leaving the page you were reading.
That removes a few steps nobody ever enjoyed.
A changelog, at last
We set up a weekly agent workflow that scans our context repos and surfaces potential changelog entries. Our former docs didn’t have a changelog, so this is as much about building the habit as the tooling. Users should be able to see what’s moving. Now they can, every Monday morning.
Every Monday at 09:00, Mintlify’s agent reads our context repos, looks at what’s been tagged since the last changelog entry, and opens a PR with high-level entries, the changes users actually see and interact with.
Easier to keep current
The maintenance side has changed too. We can point agents at our CLI, our Terraform provider, our API, and have them flag when the docs drift from the code. That’s a fundamentally different relationship with documentation than “someone will update it eventually.”
We’ve also got a GitHub workflow that rebuilds the CLI reference whenever the CLI ships a new release. Our CLI has a docs command in Go that renders every command to Mintlify’s format, so the reference stays in sync with the binary without anyone having to remember to update it.
Doc work where the conversations happen
The Mintlify Slack integration means doc changes can happen where team conversations already exist. A discussion about a customer question can turn directly into a call to @mintlify like below. No context switching. No ticket.
Writing with intent
We’ve also adopted the Diátaxis framework together with principles from the “Docs for Developers” book to bring consistency to how we write and review. A developer landing on our docs always has a reason for being there. They’re learning, they’re trying to get something done, they’re troubleshooting, or they’re integrating Kosli into their tooling and need a reliable reference. Those are different jobs, and docs that blur the lines between them quietly fail people. We now have that encoded in our Claude.md, so agents reviewing or generating content know the difference too.
Shorter feedback loops
We moved the docs out of the CLI repository into their own. Every PR now gets a live preview environment, so anyone can see exactly how a change renders without pulling it locally. The feedback loop dropped from 10-15 minutes down to 1-2 minutes.
Docs Driven Development
The combination of agentic support and live previews has also changed how we shape new ideas. We now draft the docs first, tutorials, conceptual guides, reference material, to get a tangible feel for how a change will look from a customer’s perspective before we build it. It spawns engaging conversations and shapes the end result.
The docs used to trail the feature. Now they lead it.
That’s the win
When we have an easier job keeping it current, spotting gaps early, and writing in a way that matches why someone shows up, developers hit fewer dead ends. They find what they need faster, whether they’re reading, asking an agent, or dropping into the playground. Better DevEx. That and of course dark mode!
Go have a look at docs.kosli.com and tell us what you think.
