Guides for SaaS documentation teams

Most SaaS teams do not lack a release notes template. They lack a gate: a point in the release process where someone accountable checks that the notes are true, specific, written for the reader and published on time. Without the gate, the template decays into a list of ticket titles within a quarter. This post gives you both: a template we use, and a review gate that runs in the same pull request flow as the code.

Docusaurus gives you a reasonably accessible starting point, and most sites then lose some of it. The losses rarely come from the framework itself. They come from custom colors, custom components, a sticky banner someone added for a launch, and years of Markdown written without anyone checking alt text or heading order. This post lists the WCAG 2.2 AA issues we look for first on a Docusaurus site, where each one usually comes from, and how to test for them.

When a support bot tells a customer something false, the instinct is to blame the model and start adjusting the prompt. Sometimes that is the problem. More often, in our experience, the bot is faithfully summarizing content that was missing, stale, contradictory or impossible to retrieve, and the model is the messenger. This guide is a diagnosis method: how to trace each bad answer to its cause, and which fix belongs to which cause.

Your support queue is the most honest documentation backlog you will ever get. Every ticket is a customer telling you, in their own words, what the product and the docs failed to explain. The trouble is that a queue of several thousand tickets is not a backlog yet. This is the method we use to turn it into one: a ranked list of articles to write, fix or retire, each backed by real tickets and written in the words customers actually use.

Most comparisons of Docusaurus, MkDocs and GitBook are written for developer documentation: API references, SDK guides, versioned technical manuals. A customer help center has different requirements. The people writing it are often support agents rather than engineers, the readers arrive from search with a problem, and the site has to hand off to a human when the article is not enough. This comparison is written for that case.

If your documentation runs on Material for MkDocs, nothing broke when the project entered maintenance mode, and nothing will break on the day support ends. What changes is who carries the risk. Every Python upgrade, dependency advisory and browser change after that date lands on your team, with no upstream fix coming. That makes this a planning decision, not an emergency, and the right time to make it is while the maintainers are still shipping security fixes.

A Zendesk help center that has been live for a few years usually ranks for a long tail of how-to queries nobody on the team tracks. Moving it to Docusaurus keeps that traffic only if every old article URL answers with a permanent redirect to its new home on the day you switch. How you do that depends on one question most teams have not asked yet: who controls the domain the help center is served from?

Moving a Confluence space to Docusaurus is mostly a conversion problem with three traps in it: macros that have no Markdown equivalent, a page tree that does not map cleanly to folders, and URLs that carry page IDs your redirects have to honor. This guide covers each step in the order we do it, with the commands and config we actually use.

This is the checklist we work from when a SaaS team moves its documentation off Zendesk, Confluence, Word or Google Docs and onto a docs-as-code stack such as Docusaurus, MkDocs or GitBook. It is ordered by phase, every item is something you can verify, and each phase ends with a gate: if the gate is not met, the next phase waits.

Docs as code is a shipping model, not a shopping list. Copying another company's toolchain gives you their cost structure without their constraints, and most of the cost lands on the person maintaining the pipeline rather than the person writing the page. This is which parts pay for themselves, what has to be true before each one does, and what is theater.