About Hosted Docs

Context

Teams already write docs. They already have CI. What they lack is a host that treats a published package as a versioned claim, and a chat index that does not silently become the public site. Hosted Docs is those two jobs, plus a branded reader.

Diátaxis (diataxis.fr) splits documentation because readers switch between learning, working, looking up, and understanding. Mixing those jobs in one page makes every job worse. These marketing pages, the tenant chapters, and generated QLI pages are each one type: tutorial, how-to, reference, or explanation. How-to is not a tutorial.

Why

Go-live and knowledge sync are separate because a connector pull is lossy and often private. A successful CI push becomes the live version. Sources sync fills the index for chat and agents. Confusing them is the usual demo and ops footgun.

Generate then Approve exists because a model can omit a file or stop mid-queue. The draft is a claim about a commit. Approve is the only promote. Incomplete drafts fail closed.

Trade-offs

Four types are slower to write than one mixed landing page. The gain is that a first-time publisher can follow a tutorial without a parameter table, and a working admin can open a how-to without a lesson.

Index-first chat can answer without a model call. Harder questions use AI with citations. When the index cannot ground an answer, the assistant says so instead of guessing. That is less fluent than an unconstrained chatbot, and more honest.

Further reading

Jump by type:

*(see Tutorial: Quick start)* *(see How-to: How to publish from your pipeline)*