Optimizing Developer Docs in the Age of AI: Our Mintlify Migration Story

We rebuilt our developer docs and migrated to Mintlify.

This wasn’t just a tooling upgrade. It was a shift in how we think about developer education in an AI-native world.

Watch how we reimagined developer education

In 2025, we asked ourselves a simple question: How will developers consume documentation in the future?

We’re watching a shift happen in real time. A new generation of AI-native developers is emerging, people who learn and build in ways that are faster, more fluid, and less dependent on traditional step-by-step documentation. They rely on coding agents and IDEs that expect structured, machine-readable answers, not long-form instructions. 

At the same time, we know some developers still prefer to explore and understand at their own pace. 

Understanding the new developer workflow

At HubSpot, we believe the future of documentation should work for both AI-native builders and AI-skeptics alike. Our goal is to help both finish their build as quickly as possible. 

That meant rethinking our approach: how we deliver documentation, how we support developers, and what problems we should be solving. 

We chose Mintlify not just to modernize our docs for how developers work today, but to build for how they’ll work next.

The Challenge: Context Overload

Here's the real challenge we faced: It wasn’t that AI models were pulling from outdated content, it’s that they were overloaded with too much context.

So, when a developer asked how to create a HubSpot contact, the AI would grab info from our legacy V1 API docs, current V3 API, private app examples, public app tutorials, and serverless functions - all jumbled together. The model had no clue what the developer was trying to build, so it gave conflicting advice or suggested incompatible approaches.

Our Solution: Context precision through MCP server development.

We built an MCP (Model Context Protocol) server to cut through the noise.

Instead of letting AI models sift through years of documentation and get confused by private vs. public API incompatibilities or old vs. new project versions, and conflicting guidance, we're giving them refined, targeted context.

Here's how it works: 

When you search for "create contact" through our MCP server, it doesn't just find the first result. It searches, finds the legacy v1 API, then automatically checks to see if there's a newer version of this API. It finds the current version from our live docs and creates an example using that.

So now, the AI only relies on the latest, most relevant information rather than getting tripped up on what's legacy versus modern, private versus public, or which approach actually works with what you're trying to build.

As our CEO, Yamini Rangan, says “AI is only as good as the context it's given.” And, we're finally giving models good context so they can deliver better outcomes and better responses.

MCP Server with Cursor

Building solutions like this MCP server is exactly what became possible when we stopped maintaining infrastructure and started focusing on developer innovation.

The Migration to Mintlify: Unlocking the future workstream for developers

Let's be honest about what this migration was really about: We were spending our time like a docs platform team, but our mission was developer experience. That mismatch was holding us back.

For years, we'd had discussions about buying vs. building a docs platform. Three different times, we felt it made sense to build in-house because no platform met our complex needs. But that meant we weren’t iterating on UX, we were maintaining infrastructure.

Before Mintlify, we spent most of our cycles maintaining docs infrastructure instead of actually improving the developer experience. Every feature request meant weighing it against technical debt. Every UI improvement required engineering sprints.  

We weren't a docs team, we were an accidental docs platform team.

We'd built an elaborate documentation site, but despite trying new approaches based on user feedback, the experience of finding what you needed just wasn't serving our developers. We were spending engineering cycles maintaining complicated infrastructure instead of fixing the actual problems developers were telling us about - "I only use Google to find stuff in your docs"

What buying vs. building got us: When Mintlify came on the scene, we re-evaluated again and found they could actually work with our platform, not perfectly, but getting us 90% of the way there, with willingness to work with us on custom solutions.

Mintlify gave us table-stakes features overnight that would have taken us quarters to build: proper auth, user permissions, a solid search, and an AI chat functionality. But more importantly, it gave us something we couldn't build: the bandwidth to build more for developers.

Migrating to Mintlify has opened up our bandwidth to start experimenting with the stuff that actually matters. We're building MCP servers that give AI tools surgical access to exactly the right information. We're scoring our docs to understand what's confusing and what's working. We're treating AI readability as a first-class concern, not an afterthought.

The migration wasn't about moving content. It was about admitting that maintaining a docs platform wasn't our core competency. Helping developers build with HubSpot was.

New Docs Workflow

The Mintlify Advantage: Designed for AI and Humans

Here's what we discovered: you can't optimize for both humans and machines by accident. It requires intentional design choices that most documentation platforms just don't make.

For developers using AI tools: Mintlify structures everything in a way that makes sense to both ChatGPT and the human asking ChatGPT the question. 

Think of it this way, when you ask ChatGPT or Cursor for help with code, it needs to find and understand your documentation just like a human would. But AI tools are  literal. They need consistent code examples, clear parameters, and structured responses.

Before, when a developer asked their AI assistant "How do I create a HubSpot contact?" they might get outdated code mixed with current examples, or suggestions that technically work but miss important context. 

Now they get working code, plus the context they need to understand what it’s doing. Not a philosophical discussion about contact management.

For developers who prefer to read and explore: The navigation doesn't assume you know what you're looking for. Pages load faster, search finds what you need, and AI prompts help you discover related content. You can browse, drill down, and follow logical paths. 

What it solved for our team: Remember the last time you tried to publish something and spent hours on a build, only to run into last-minute deployment conflicts? That's what our old system felt like every day.

Mintlify converts markdown to HTML and handles all the technical complexity we used to wrestle with. Our tech writers can push changes directly through Git - no more waiting for engineering cycles or monitoring complex deployment pipelines. What used to take hours to deploy now happens automatically. The docs-as-code approach we started transitioning to earlier this year finally works the way it should: reviewable PRs, full revision history, and bulk updates that deploy reliably.

Here’s the best, but also unexpected, part. When your docs platform makes it easy to be clear and consistent, your writing actually gets better. It's like having a really good editor who won't let you publish something confusing just because it looks nice.

So yeah, we thought we were buying a docs platform. Turns out we bought ourselves the ability to focus on what actually matters: helping developers ship.

What's Next: Building for Tomorrow's Developers

The future of developer docs is still being written, so we won’t sit here and tell you we have all the answers. 

As our tech writer Eric Devenney puts it: "We're still learning how and when to use AI as a tool, but tinkering is one of the fun parts of our job!"

What we will say is that migrating our docs to Mintlify has positioned us to tackle the real challenges in developer docs. We're not just maintaining docs anymore, we're actively optimizing how developers discover, consume, and apply information in an AI-first world.

We're building MCP servers that eliminate the confusion between legacy and current approaches. We're developing systems to score and improve our content based on both human and AI consumption patterns. We're creating feedback loops with our developer community that help us understand what's working and what isn't.

Experience the Difference

Our goal was not just to make our docs AI-friendly. It was to make them work seamlessly across every way developers might encounter them in their workflow. 

Whether you’re asking ChatGPT at 2 AM, methodically reading through examples during your morning coffee, or frantically copying code snippets while your boss asks when the integration will be done - we built docs that meet you where you are. 

Ready to see it in action? Explore our new developer documentation and try building something. Whether you're AI-native or AI-skeptic, we think you'll finish your build faster than ever before.

Let us know what breaks. Hit the thumbs up or down on any doc page to share feedback.