What to require of a customer-facing docs platform

Your public docs are part of the product. Customers decide with them, support quotes them, and partners build on them. When a page is wrong, it is your company that said it.

Most comparisons of docs tools start with the editor and the theme. Those matter, but they are easy to judge in a demo. The requirements below are harder to see in a demo and harder to fix later: who approved a sentence, who can see it, and whether you can show what a reader saw last March.

A public page should never change because someone pressed save. Every edit, whether a typo fix, a new limit or an update drafted from your API, should reach readers only after someone responsible has read it.

The test is simple: pick any sentence on the live site and ask who wrote it, who approved it and when it went out. If the tool cannot answer for one sentence, it cannot answer for the site.

Most companies write for more than one reader. A visitor needs the basics, a customer needs the steps in their dashboard, a developer needs the endpoint, and a partner needs the terms that apply only to them.

The usual answer is a copy of each page per audience. Copies drift apart, and the one nobody looks at goes wrong first. Ask instead for one page, kept once, where each part says who it is for.

Readers judge a docs site in the first second: the address in the browser, the name on the tab, the preview when a support agent pastes a link into a chat. If any of those names another company, readers notice.

Require your own domain, with the certificate handled for you, and your own name, colours and logo on every surface a reader sees.

Sooner or later a customer writes: “your docs said something else when I signed up.” Without a record, that becomes their word against yours, and the person answering has to guess.

Require that any page can be opened as it stood on a given day, with the version and its approval, and that published versions cannot be edited afterwards, even by an administrator.

Readers increasingly ask instead of browse. An assistant on your docs speaks for you, so it should be held to the same standard as a page: it says only what your published docs say, and shows where.

Three questions catch most failures. Ask about a recent change, to see whether the answer is current. Ask a visitor’s question whose answer sits on a partner page, to see whether it leaks. Ask something the docs do not cover, to see whether it admits it.

You need to know which pages are read and which are skipped. You do not need to follow your readers to know it. A docs site that drops an advertising tag on every page owes its readers a cookie banner, and your legal team an explanation.

Ask to see the request a page view sends. It should be short enough to read in full.

None of this matters if moving in means freezing the docs for a month. Ask how your current pages arrive, and what happens before they go live.

Good answers: from a link to your current site, from files you upload, or from text you paste, with structure kept, arriving as drafts your team reviews like any other change. Your old site stays up until you point your domain at the new one.

Rate the tool you use today against each requirement. Your ratings stay in this browser, and you can copy the card into your evaluation as a table.

Further reading

How review and approvals work: Review and publish. Domains, themes and analytics: Publishing and brand. How Gravity protects your content: the security brief.