Skip to main content

The real cost of documentation vendor lock-in

· 6 min read
voix
Documentation studio

Documentation lock-in is almost never visible when you sign up. The editor is pleasant, the hosting is included, search works. You find out what lock-in costs on the day you try to leave: when the export turns out to be a folder of HTML with vendor markup, the URLs belong to someone else's domain, and three years of review history stays behind. The subscription fee is what you pay to stay. The exit cost is what you pay to go, and it is the number worth knowing before you need it.

We spend much of our time moving SaaS documentation off Zendesk, Confluence, Word and Google Docs. The migrations that go badly are rarely the ones with the most pages. They are the ones where nobody priced the exit until the renewal deadline forced it. So this post is not a migration checklist; we wrote one of those separately, the documentation migration checklist. This is about how lock-in actually works, and how to keep it cheap.

Lock-in is an exit cost, not a license fee​

A platform that costs a lot but lets you leave in a week is not locking you in. A free platform that would take six months to leave is. The useful definition is: lock-in is the cost of leaving, measured in engineering time, lost traffic and lost history.

That cost has four parts, and each one grows quietly while you use the platform.

1. Content format​

Where does your content actually live, and in what shape? If the answer is "in the vendor's database, rendered as HTML with their own markup", every page you write adds to the conversion bill. Proprietary macros are the worst of it: callout panels, include blocks, dynamic tables and page trees that only exist inside the platform. Each one needs a conversion rule, and each rule needs testing.

Plain text formats such as Markdown are cheap to leave because almost every documentation tool reads them. That is the whole argument for docs as code, and it is a stronger argument than any feature list.

2. URLs​

Your documentation URLs collect links from support replies, in-product help buttons, partner guides, community answers and search results. If those URLs live on a vendor's domain, or follow a pattern only the vendor can serve, you cannot redirect them when you leave. A help center on yourcompany.vendor.com is a help center whose search rankings belong partly to the vendor.

The cheapest insurance is a custom domain you control from day one, even if the vendor hosts it. Then leaving means repointing DNS and serving redirects, not abandoning every inbound link. Our post on redirect mapping covers what those redirects involve.

3. Workflow and history​

Who changed this page, when and why? In a hosted editor, that history lives in the vendor's revision log, and it rarely survives an export. Neither do review approvals, comments or the reasoning behind a decision. Teams underestimate this until an auditor, a lawyer or a new docs lead asks why a page says what it says.

When content lives in Git, the history is part of the content. It moves with it.

4. Integrations​

This is the part that grows fastest. The help widget in your product, the article suggestions in your ticketing tool, the search integration, single sign-on for internal docs, and increasingly the AI assistant trained on your help center. Each integration is a reason the platform is useful, and each one is a thing to replace on the way out.

How to price an exit before you need one​

You can estimate your exit cost in a day, without committing to anything. We call it an exit drill:

  1. Export one real section, using whatever export path the platform offers. Not a demo space; a messy section with tables, screenshots and a few macros.
  2. Convert it to Markdown with whatever generic tool is at hand, and build it in any static site generator.
  3. Count what broke: macros that disappeared, tables that collapsed, images that no longer resolve, internal links that point at the old host.
  4. List the URLs in that section and check whether you could redirect them from a domain you control.
  5. List the integrations that read from that section.

Multiply by the number of sections, adjust for how representative the sample was, and you have a rough exit cost. It is usually either reassuringly small or alarmingly large, and both answers are useful. The handbook page on deciding whether to migrate turns that estimate into a go or no-go decision.

Lock-in you choose on purpose​

Not all lock-in is bad. Paying a vendor for hosting, search or a visual editor is a reasonable trade if the exit stays cheap. The distinction we draw for clients is between lock-in on services and lock-in on assets.

Services are things you could buy elsewhere: hosting, CDN, search, analytics, a nice editor. Being tied to a vendor for these is an inconvenience. Assets are things only you have: the content, its history, its URLs and the structure that makes it findable. Being tied to a vendor for these is a strategic risk.

So the rule is simple. Rent services freely. Keep the assets in formats and on domains you control. A hosted platform with Git sync to your own repository and a custom domain can be a perfectly good choice; a hosted platform where the only copy of your content is in their database, served from their subdomain, is a liability that grows every month.

Questions to ask any documentation vendor​

Before signing, or before the next renewal, ask these in writing:

  • Which export formats are available, and does the export include every page, attachment and revision?
  • Is there an export API that can run on a schedule, without contacting support?
  • Can the docs be served from a domain you control, with permanent redirects?
  • When the account closes, what happens to the existing URLs on that day?
  • Which integrations depend on content stored only in the platform?

Vague answers to any of these are an answer.

When staying is the right call​

None of this means every team should migrate. If your content is small, your URLs are on your own domain, the export is clean and the integrations matter more than flexibility, staying is often the sensible choice. The point of pricing the exit is that you stay because it is right, not because leaving has become too expensive to contemplate.

If the drill tells you it is time to move, our documentation migration service moves content, URLs and history onto a stack you own, from $4,500 for up to 150 pages. Send us your current platform and a rough page count through the contact page. We reply within 1 business day.