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.
The problems don't show up in week one. They show up in month six, when your API has 150 endpoints, three developers are editing docs simultaneously, you're shipping spec updates weekly, and your enterprise customers start asking about SSO access to your private docs.
Here's the timeline of how things broke for us, roughly in the order we discovered each pain point.
The 7 Problems That Actually Made Us Quit
I'm not going to list eleven problems because some of them are annoyances, not dealbreakers. These are the seven that cost us real engineering time or blocked real customer requirements.
1. The Spec Overwrite Problem (The Big One)
This is the issue that slowly ate our documentation quality alive.
GitBook's OpenAPI integration only overwrites. It doesn't merge. Here's the workflow that drove us insane for eighteen months:
Our technical writer spends three hours enriching endpoint descriptions, adding context, authentication tips, usage notes, edge case warnings. Then a developer pushes an updated OpenAPI spec with two new endpoints. GitBook nukes every manual edit and replaces everything with the raw spec.
No merge. No diff. No warning. Just gone.
You can't have both an accurate spec and useful documentation at the same time. Every spec update resets the docs to the bare-metal auto-generated state. For a team shipping weekly API updates, this meant choosing between accuracy and quality, and then spending hours manually re-adding the enrichments that got wiped.
A Hacker News user captured the core issue: maintaining an OpenAPI spec and a separate GitBook felt like doing the same work twice. It is. Because GitBook treats your spec as a thing to render, not a thing to collaborate on.
2. API Content You Can't Actually Touch
Once an OpenAPI block renders in GitBook, the content is essentially read-only. You can't add inline notes to specific fields. You can't attach warnings to deprecated parameters. You can't link related endpoints together within the reference itself.
Each OpenAPI block shows a single operation, so if you have 150+ endpoints, you're managing 150+ blocks. That's not documentation. That's data entry. And if someone reorders the sidebar, every block reference can break.
This matters because the gap between auto-generated API docs and good API docs is huge. Good docs have context: "this endpoint returns paginated results, use the cursor parameter from the response's meta object for the next page." Auto-generated docs just list the parameters and hope for the best.
3. Their API Testing Isn't Even Theirs
This one surprised us the most, and it's the detail that reframed how we thought about GitBook entirely.
GitBook's "Try It" API testing feature, the interactive playground where developers can test endpoints directly from the docs, isn't built by GitBook. They embed Scalar, a third-party tool, inside their interface.
Think about what that tells you. The single most critical developer experience feature in API documentation, the thing that separates useful docs from a glorified PDF, and they outsourced it. They didn't build it because they're not an API documentation platform. They're a wiki that added API rendering as a checkbox feature.
And it shows. Authentication flows are clunky. Environment switching is limited. There are no pre-request scripts to generate tokens dynamically. No chained requests where one endpoint's response feeds into another. No environment variables to switch between staging, sandbox, and production. No request signing for APIs that use HMAC or similar auth.
For teams with straightforward GET-request-with-an-API-key APIs, the Scalar embed is fine. For anything involving OAuth2 token chains, HMAC signing, multi-step auth flows, or environment-specific configs (so basically any enterprise API), your developers will open Postman anyway. Which means your "interactive docs" aren't actually interactive where it matters.
This was the moment we stopped thinking of GitBook as an API docs platform that needed improvement and started seeing it for what it is: a solid wiki with an API rendering feature bolted on the side.
4. The Pricing Surprise
GitBook's pricing page says $8/user/month. That's technically true and practically misleading.
Here's the real math for a 10-person team with 3 documentation sites:
- User fees: 10 × $12/month = $120/month
- Per-site fees (custom domain): 3 × $65/month = $195/month
- Total: $315/month minimum, before AI add-ons
Their free tier went from 3 users to 1. Custom domains that used to be free now require the Premium tier. AI features, which they market aggressively, are gated behind Premium with opaque usage limits.
One user on Trustpilot reported a roughly 5x cost increase after pricing restructuring. Another reported being charged $585 for a plan they'd already canceled. GitBook currently sits at 1.9/5 on Trustpilot with 73% one-star reviews. I'll let those numbers speak for themselves.
The pricing issue isn't just about money. It's about trust. When free features become paid features retroactively, you can't build a long-term documentation strategy on the platform with any confidence that next year's costs will resemble this year's.
5. No API Changelog Generation
Every time our API changed (new endpoint, deprecated field, modified response structure), someone on the team had to manually document what changed, when, and what it breaks. There's no diff detection between spec versions. No automatic breaking change alerts. No version comparison view.
For a team shipping weekly API updates, this is hours of manual busywork per release. And because it's manual, things get missed. A field gets deprecated silently. A new required parameter appears without a migration note. Our API consumers discover breaking changes when their integrations fail in production.
This is the one that offended my DevOps sensibilities the most. We have automated diff detection for every other config file in our stack. Our API spec, arguably the most important contract we publish, gets manual changelog management. In 2026.
6. No Notification System for API Consumers
Here's a scenario: you push a breaking change, update your documentation, and none of your API consumers know about it until their code breaks.
GitBook has no subscription mechanism for doc changes. No email notifications when endpoints update. No RSS feeds. No webhooks. No "watch this endpoint" functionality. Your developers have to manually check your docs and hope they notice what's different.
For a platform that charges enterprise prices, the absence of a basic notification system is hard to justify. Every other SaaS product we use, from GitHub to Datadog to our own product, has change notifications built into its core. Our documentation platform doesn't.
7. Leaving Is Deliberately Hard
This is the one I wish someone had warned us about before we moved in.
GitBook has no direct Markdown export. To get your content out, you have to set up Git Sync with a GitHub repo, wait for the sync, clone the repo, and then discover that the "Markdown" is full of proprietary block formats that don't render as standard Markdown anywhere else.
The export is lossy. Custom blocks, interactive elements, and GitBook-specific formatting don't survive the trip. Cross-space links break. Comments and page history are lost. You'll spend hours cleaning up files before they're usable in any other system.
The fact that Astro and ChainSafe both published dedicated "Migrating from GitBook" guides tells you how common, and how painful, this migration is. When multiple platforms have to build escape tools specifically for your product, that's a signal.
How We Evaluated Replacements
I'm a DevOps engineer. I evaluate tools the way I evaluate infrastructure: with a requirements matrix, weighted scoring, and actual testing. Not vibes.
We evaluated six platforms over three weeks: ReadMe, Mintlify, Docusaurus, Redocly, Theneo and Fern. Here's the honest breakdown.
The Requirements We Tested Against
These came directly from our eighteen months of GitBook pain. Each one was a real problem we'd hit, not a hypothetical:
- Spec merging : Can we push an updated OpenAPI spec without losing manual enrichments?
- Editable API content : Can we modify field descriptions, add context, and link endpoints inline?
- Automatic changelog : Does the platform detect spec diffs and generate changelogs?
- Consumer notifications : Can API consumers subscribe to updates?
- API testing : Is the playground native, with pre-request scripts and environment variables?
- External SSO : Can enterprise customers authenticate with their own identity providers?
- Custom branding : Full CSS control, no vendor branding forced on our pages?
- Export/portability : Can we get our content out cleanly if we need to leave?
- Pricing transparency : Is the pricing straightforward, or are there per-site fees and hidden add-ons?
What We Found
Docusaurus was the strongest self-hosted option. Open source, React-based, full control. But it's a static site generator, not a documentation platform. You get total freedom and zero managed features: no API playground, no changelog automation, no AI assistance. For a team of three that doesn't want to maintain a custom docs pipeline, this was too much infrastructure.
ReadMe has strong API documentation features and a solid editor. The pricing gave us pause. It gets expensive at scale, and some critical features are enterprise-only. The API testing was better than GitBook but still felt like it was bolted onto a general docs platform rather than built from the ground up.
Mintlify has a beautiful default design and great developer experience. But we had concerns. There was a security incident in 2024 where customer GitHub tokens were exposed, and while they handled the response well, it factored into our risk assessment. Their API-specific features (changelog generation, spec merging) were less mature than some alternatives.
Redocly is strong on OpenAPI rendering, probably the best pure spec renderer we tested. But it leans toward being a development tool rather than a full documentation platform. The editing experience for non-technical team members wasn't as smooth, and the portal/catalog features were less developed.
Fern has an interesting approach: you define docs in a fern/ folder with config files, and it generates everything. Great for developer-led docs teams. Less great when your technical writer needs to make a quick edit without opening a code editor and pushing a commit.
Theneo. Full disclosure: this is where we ended up, and I'll explain why. But I want to be clear about what it is and isn't.
Where We Landed (And What Actually Changed)
We migrated to Theneo. Here's the honest version, both what improved and what I'd want them to fix.
What solved our actual problems:
The spec overwrite problem disappeared. This was the biggest single improvement. Push an updated OpenAPI spec and your manual enrichments survive. The editor and the spec coexist instead of fighting each other. For a team that spent eighteen months losing work to blind overwrites, this alone justified the switch.
API content became something we could actually edit. Every field, description, and example is editable inline. Our technical writer can add contextual notes to individual parameters without worrying that the next spec push will destroy her work.
Automatic changelogs from spec diffs. Push a new spec version and the platform detects changes (new endpoints, modified parameters, deprecated fields, breaking changes) and generates a changelog. No more manual release notes. No more customers discovering breaking changes from 500 errors.
Their documentation AI is genuinely different from a ChatGPT wrapper. They built it in 2022, before the ChatGPT wave, specifically for API documentation. It generates field-level descriptions, creates realistic example payloads, and produces code samples in multiple languages. Whether it's good enough depends on your API complexity. We still review and edit everything but it cuts our documentation time from ~20 hours per week to under 5.
Pricing that doesn't play games. All features included. No per-site fees. No AI usage caps. No surprise invoice. After GitBook's pricing trajectory, the transparency alone was a relief.
What I'd be dishonest not to mention:
It's a smaller company. GitBook has brand recognition and a larger ecosystem. If you value the "nobody gets fired for buying IBM" factor, that matters. Theneo powers docs for 17,000+ companies including some major names, but it's not the default choice everyone's heard of.
The editor takes adjustment. If you're coming from GitBook's block editor, Theneo's approach feels different. Not worse, just different. Our team needed about a week to feel fully comfortable.
Some features are newer. Their wiki portal features are more recent additions. They work, but they don't have years of battle-testing that some competitors' core features do.
The Migration (It Took a Day)
Here's the actual process, in case you're staring at your own GitBook and wondering how painful the move would be.
Step 1: Gather your specs. If you have your OpenAPI/Swagger files separately (most teams do, since they're what you imported into GitBook), use those directly. If GitBook is your only copy, set up Git Sync, clone the repo, and extract them. You can also use Postman collections. Theneo imports OpenAPI 3.x, Swagger 2.0, GraphQL, and gRPC.
Step 2: Import and let the AI work. Create a project in Theneo, import your spec, and the AI generates initial documentation: descriptions, examples, code samples. What took us weeks to write manually in GitBook was generated in minutes. Not all of it was perfect, but 80% was good enough to ship with minor edits.
Step 3: Enrich the parts that matter. Don't try to perfect everything at once. Focus on your most-used endpoints first. Add authentication context, usage notes, edge case warnings. The stuff that turns auto-generated docs into actually-useful docs.
Step 4: Set up your domain and branding. Point your custom domain (included, not a $65 add-on), upload your logo, set brand colors, apply custom CSS if you need to match your product's design system.
Step 5: Redirect and announce. Set up 301 redirects from your old GitBook URLs. Update links in your README, onboarding emails, and API error responses. Notify your API consumers and tell them they can now subscribe to doc updates, because that's a feature they never had before.
The whole migration, including testing, took less than a day. The cleanup of GitBook's proprietary Markdown format took longer than the actual import into Theneo, which tells you everything about the lock-in problem.
The Decision Framework (For Anyone Evaluating)
Forget my specific choice. Here's how I'd evaluate any documentation platform, based on what I learned from eighteen months of pain:
Ask these questions before you commit:
What happens when I push an updated spec? If the answer is "it overwrites everything," run. Your team will stop enriching docs within a month.
Can I edit the rendered API content? If the API reference is a black box that just renders your spec, your docs will always be bare-minimum.
How do I leave? Try exporting before you commit. If the export is lossy or proprietary, you're signing up for lock-in. Factor that into your total cost.
What's the real price? Add up per-user fees, per-site fees, feature add-ons, and AI costs. Then ask what happens to pricing in twelve months. Check Trustpilot. Check Capterra. The invoice is the real review.
Who built the API testing? If it's a third-party embed, API documentation isn't the platform's priority. You want a team that builds the testing experience themselves because they consider it core to the product.
What does the notification system look like? If your API consumers have no way to subscribe to changes, you'll be fielding support tickets every time you deploy.
Your documentation is infrastructure. Evaluate it like infrastructure, with real requirements, real testing, and a real exit plan.
Top comments (0)