We Used GitBook for Two Years. Here's the Honest Post-Mortem of Why We Left

I've spent the last four posts in this series tearing into AI agent frameworks, MCP, deploy automation, and CLAUDE.md configs. Today's post is different. It's about documentation infrastructure. And if that sounds boring, consider this: your API docs are the first production system your customers interact with, and most teams treat them with less rigor than a README. We used GitBook for almost two years. When we started, it genuinely felt right: clean editor, decent Git integration, fast setup. By month eighteen, we were fighting the platform more than we were writing documentation. This is the post-mortem of what went wrong, what we learned while evaluating replacements, and where we landed. Fair warning: I have opinions. But I'll show my work. How It Started vs. How It Was Going GitBook's onboarding experience is legitimately good. You sign up, paste your OpenAPI spec, and you've got rendered docs in under ten minutes. For a small team shipping a v1 API, that speed is intoxicating. T