5 posts tagged with "Docs Architecture"

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.

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.

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.