Guides for SaaS documentation teams

Content conversion is the visible part of a migration and the part that rarely fails. The part that fails is the URL layer: every bookmark, support macro, in-product help button, partner page and search result that points at the old docs. A redirect map keeps those working, and it is usually built last, in a hurry, by whoever is still awake.

Every migration proposal contains the phrase "content audit", and almost nobody says what comes out of one. It is not a reading exercise, and it is not a quality score out of ten. It is a classification pass that ends with one decision per page, a count next to each decision, and a named person who agreed to it.

Your documentation now has a second audience. Besides the customers and support agents who read it, there are support bots, in-product assistants, AI search engines and your customers' own AI tools, all pulling passages out of your docs and presenting them as answers. These readers do not browse your navigation, do not notice that a page is three releases old and do not know that two pages contradict each other. Whether they give good answers depends far less on which AI product you buy than on decisions about your content that most teams have not made yet.

In many SaaS companies, documentation is a checkbox on the release ticket: "Update docs". Someone ticks it the day before launch, or the day after, or never. The docs are treated as a deliverable that comes after the real work, rather than as part of the product customers use. The cost of that shows up everywhere except in the docs budget: in support queues, in sales engineering time, in onboarding calls and, more recently, in support bots that confidently repeat whatever the docs got wrong.

A documentation migration has a launch date, and most of the planning points at it. Content is converted, redirects are tested, the new site goes live, and everyone relaxes. Then, over the following months, something quieter happens: pull requests wait a week for review, one team goes back to editing the old wiki, a dependency upgrade gets postponed twice, and the new platform slowly becomes as hard to run as the one it replaced. Migrations rarely fail at cutover. They fail in the handover nobody scoped.

Documentation information architecture usually starts as a sensible list of sections that matched the product on the day someone created it. Then the product grows: a second product line, an enterprise plan, a mobile app, an acquisition, three reorganizations. Each change adds a section or a subsection wherever it fits least badly, and a few years later the navigation is a fossil record of the company's history rather than a map of what customers need to do.

Good writing helps a reader who is already on the right page. Good structure gets them there, tells them within seconds whether they are in the right place, and lets them find the one step they need without reading the rest. When we review a help center that customers say is "hard to use", the prose is rarely the problem. The problem is that every page has a different shape, so readers cannot predict where anything will be.

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.