Documentation and FAQ spaces

Two space types cover reference material readers arrive to consult: Documentation (a nested tree of pages) and FAQ (a flat list of question/answer pairs on one page). Both are "page-backed" — you author pages, not threads — but they render very differently, because a person reading docs is exploring and a person reading an FAQ wants the answer in front of them.

Documentation (DOCS)

A documentation site: guides and reference, arranged in a nested tree. Pages live in collections, the collection holds pages, and pages nest into a tree that becomes the reader's navigation.

Set it up

1. Create a space and choose the Documentation type. Its public prefix is /p/.

2. Add a collection (the top-level container), then add pages inside it. Pages can be nested under other pages to build the tree.

3. Pick a layout preset in Design (see below).

4. Staff author the pages; the type is staff-only for creating content.

The four layout presets

Choose one in the space's Design tab. Each is a whole arrangement, not a bag of toggles:

• Guide (recommended) — the page tree beside the writing, an on-this-page rail, and previous/next links at the foot.

• Reference — the tree and the page, nothing else. For material read in a hurry by someone who already knows why they are there.

• Minimal — just the page, no tree and no rail. For docs that are really one document.

• Landing — a real front door: your intro, a search box, and each section rendered as a card. Pages inside keep the Guide layout.

When the preset is Landing, the space root renders a hero + search + section cards instead of redirecting to the first page.

Per-page facts you can declare

Each page can carry declared fields that tell a reader what they need to know before they read:

• Written for (audience) — who should be reading this. The difference between "this is not for me" and ten wasted minutes.

• Deprecated (deprecated, a toggle) — banners the page as still here for the people who need it, but plainly not the current way.

• Applies to (appliesTo) — the versions, plans, or platforms this page is true of (e.g. "v4 and later").

A page also tracks a verifiedAt date ("last checked") shown to readers.

Versions and languages

A docs space supports multiple versions of the same page. When a page has more than one version, readers get a version switcher, and the nav re-scopes to the version (and language) they are viewing. Version and locale are carried as ?version= and ?locale= on reader URLs.

Reference pages with live API playgrounds (OpenAPI)

The Reference preset is built for API docs. A documentation page can contain an OpenAPI block: it renders your operations as a static reference and mounts an interactive API playground ("Try it") into each operation, so a reader can call the endpoint from the page. The static reference renders even without JavaScript; the playground hydrates on top of it.

You can import an OpenAPI spec to generate reference pages. Imported operations can be given a slug prefix so they coexist with hand-written pages in the same space.

What readers get on a page

The docs reader includes an on-this-page rail, a glossary (terms defined once and highlighted throughout), page feedback ("was this helpful"), Ask AI (see the AI guide), reader search, page comments, announcement banners, and auto-generated social cards. Every page publishes its own canonical URL and SEO metadata.

FAQ

The questions you answer over and over, answered once. An FAQ is deliberately shallow: sections group questions, and every answer is one click — never two — from the list.

Set it up

1. Create a space and choose the FAQ type. Its public prefix is /faq/.

2. Add questions. Group related ones with the Topic field, or organise them into named sections.

3. Pick a preset (below). Staff author the questions.

The two presets

• Sectioned (recommended) — every answer open, grouped by topic, each with an anchor you can link to directly.

• Accordion — questions closed until clicked. For a long list scanned by eye.

Per-question fields

• Topic (topic) — groups this question with the others like it (e.g. "Billing").

• Asked by (audience) — who tends to ask this, when the answer differs by who is asking.

The answer, structured

Each question declares three parts:

• Answer (required) — answer it in the first sentence, explain after.

• The short answer — one or two sentences; most people read this and stop, which is a success.

• If that was not it — a list of the questions people ask next.

What readers get

The whole FAQ renders as one page with all questions and answers (crucial: a search engine can lift the whole thing into a result). It emits FAQPage structured data built from the same text readers see, includes a client-side filter/search box, and can link out to your contact page for anything not covered.