How Windsurf writes docs

At Windsurf, a leading player in the AI coding space, documentation is integrated in how they build, ship, and market their product.

We sat down with product marketer Robert Hou, who's been instrumental in embedding documentation into the team's release cycle.

From aligning with product launches to a rigorous analytics loop, Windsurf takes a uniquely thoughtful approach in treating docs as product.

Let's unpack how they do it.

Documentation embedded in marketing

At Windsurf, documentation is led by marketing, which is a strategic move that enables tight operations with how features are released.

Robert owns the docs process, translating feature briefs into clear, user-centric pages and working closely with engineers to get the details right. Docs ship as part of every release cycle—what Windsurf calls “Waves”—and are treated as a launch-critical component, not a follow-up task.

“We want everything clicking on all cylinders for our waves,” he shared. “The docs are an important part of getting users to the aha moment as quickly as possible.”

Product analytics as prioritization signal

Unlike many organizations, Windsurf doesn't solely rely on page views to decide which docs need attention.

Instead, they focus on product analytics, monitoring adoption after each release and using that data to guide improvements. If a feature underperforms, it's a signal to:

1. Improve discovery
2. Revisit the documentation

“We treat docs as a key lever in driving adoption,” Robert said. “If a feature isn't being adopted, sure, the feature might not actually be that useful. But on the other hand, it's also a signal that maybe the documentation and/or feature discovery could be improved.”

Writing for user goals, not technical details

One of Windsurf's early challenges was that the docs were too granular. Much of the documentation went a bit too deep into technical details and didn't help users get started.

They eventually found much better results then they focused on end value to the user first.

Now, each page starts with a value-driven explanation of what the feature does and why it matters. Everything else in the doc supports that initial user-focused framing, and technical details are layered in only when necessary.

This customer-centric approach helps all kinds of people—from seasoned developers to vibe coders—get to their value moment faster.

Vibe documenting with Windsurf

Naturally, the Windsurf team uses Windsurf to incorporate AI into their documentation process.

Robert sometimes enlists the help of Windsurf's AI agent, Cascade, to help generate an initial draft. He'll feed it a product or feature brief and prompt it to write in the style of their existing documentation.

“Now that our documentation is quite extensive, it's easy to leverage Cascade to generate new content with a structure and tone consistent with the rest of the documentation,” he said.

AI brings speed and consistency, and the team thoroughly reviews the generations to ensure quality.

Why documentation is treated like product

Windsurf's explosive growth is no accident—they obviously care deeply about the craft of both their product and their documentation. That attention to detail shows in everything they ship.

As Robert put it, “Developers today have a lot of options, and many will go with the tool that feels good. We want our product and the experience around it, including docs, to evoke positive emotions.”

That's why they've invested in the right systems and tools—including Mintlify—to help make that experience as world-class as possible.

Inspired by how AI leaders like Windsurf approach docs? Let's talk.