Documentation Guidelines

Product documentation is the reader-facing site at https://<product>.wisent.com/docs. It is not the README (the product contract), not onboarding (first success in the repository), and not marketing (the landing page above it).

Who is writing decides which cage applies. Documentation written and reviewed by people — the restored Wisent corpus is the exemplar — is held to this contract as written: structure, kinds, honesty, named drift checks. It is also, together with the 50-reference evidence set below, the writing standard AI must match when generating or updating documentation: same page kinds, same anatomy, same sourcing discipline. Machine-authored plans (the Kronika pipeline) carry the additional mechanical cage — per-block claim evidence, schema-closed kinds — because the failure mode being caged is

• The full-text crawl dataset — spis corpus at ~/.spis/docs-corpus/<NN-slug>/pages.jsonl.gz (live crawl started 2026-08-23; 85k+ pages from the first observability vendors on day one, ~941k URLs inventoried in total). Adds what journeys cannot see: real page length distribution, heading vocabulary at scale, title branding, and localized mirrors. Cited below where it sharpens a rule.

Every rule below names its source. Four sources exist:

• The operator's own documentation corpus — the Wisent library documentation written at wisent.com/documentation (state at wisent-landing-new@ff59cf6, 2026-02-18: 77 pages).
• The evidence set — 50 documentation site examples, curated 2026-08-16: search-journey recordings and interface observations.
• The content-structure dataset — content-structure/, captured 2026-08-19: per-site navigation, full page inventories (~941k URLs across 50 sites), and h1/h2 page anatomy (647 pages). Every frequency quoted below is reproducible from its per-site JSON records.

1. Layout, navigation, and shared web identity

• Sidebar beside a reading column (47/50 references are sidebar-content or sidebar-content-inspector; the corpus used the same shape), implemented as DocumentationLayout from @wisent-ai/components — one layout, no per-product shells (operator decision, 2026-08-19).
• Sidebar order: flat guide links first, then collapsible topic groups, then a reference tail (corpus shape). Every page is reachable from the sidebar.
• Content stays with the product; the portal only routes (operator decision, 2026-08-19). wisent.com/documentation is a catalog, never a copy.
• One Wisent favicon on every product landing page — use the canonical landing-cli/assets/favicon.svg; generated sites receive it as src/app/icon.svg through landing generate, and existing sites receive it through landing sync-assets (operator decision, 2026-08-25). Product repositories must not draw, recolor, or maintain their own favicon. A favicon change is made once in landing-cli, then synchronized to every landing page.

2. Content kinds

A product's docs are assembled from these kinds, in three roles. Frequencies: sites out of 50 in the content-structure dataset, unless marked in-page (647-page anatomy sample).

Guides — lead the reader to results

1. Overview — what the product is, what it owns, where to start (overview/introduction in-page at 20/50).
2. Quick start — install → first observable result, paste-ready commands (getting-started/quickstart at 30/50; installation/setup is the most common in-page section, 21/50). The corpus put Quick Start first.
3. Task guides — one per workflow, named by the task (guides/how-to 29/50, tutorials/learn 31/50). Deployment and production operation are ordinary task guides (18/50).
4. Examples — embedded in the pages they illustrate (in-page example sections 11/50); a collected Examples page may close the tail (corpus).

Reference — lookup with a uniform anatomy

5. Concept reference — one page per contract-bearing concept (concepts/architecture 10/50; the corpus' Primitives/Reading/Control/Evaluation groups), plus Definitions when vocabulary outgrows the pages (glossary 7/50; corpus).
6. Command reference — one entry per command: name as heading (monospace), Basic Usage block, variant examples, argument tables (Argument | Default | Description) grouped by concern (CLI 22/50; in-page: parameters 7/50, usage 7/50, returns/output 6/50).
7. Machine API reference — products with HTTP/programmatic surfaces document routes/calls, request and response shapes, auth (36/50, the most common kind; the corpus had a whole Python API page).
8. Configuration reference — every key a reader can set: name, default, effect (13/50; corpus: config command pages and the global Arguments page).
9. SDK / client libraries — for products that ship them (15/50).

Truth over time — what changed, what breaks, what it costs

10. Changelog / release notes — 30/50, the second most common kind after API reference. A product with shipped versions documents what changed.
11. Migration / upgrade guides — 23/50; appear with the first breaking change, not before.
12. Versions / compatibility — 12/50 sites version their docs; 14/50 in-page. See §4 for the Wisent rule.
13. Troubleshooting / error reference — 15/50. The corpus' Common Issues is this page; error codes get tables like arguments do.
14. Security — 26/50 carry dedicated security content. Facts live on the page they concern; the reader-facing security position (reporting, supported versions) is collected where a reader looks for it.
15. Pricing / limits / quotas — 14/50 (12/50 in-page). Any limit a reader can hit is documented with its number.
16. Support — community/support at 34/50. The corpus FAQ closed with a help block ("Still have questions? We're here to help!"); readme-guidelines make the support position mandatory. The docs tail ends with where a stuck reader goes.

Optional, only with honest sourced content: FAQ (9/50; corpus), contributing (11/50), videos (8/50), accessibility statements (8/50), best practices (5/50), cookbook/recipes (3/50), roadmap (2/50 — rare outside Wisent; only if it visibly separates shipped from planned).

3. Page anatomy

From the corpus and the 647-page anatomy sample:

• One h1, a one-paragraph lede stating what the page delivers, then h2 sections (the recurring in-page vocabulary: overview/introduction, prerequisites 14/50, usage, parameters, returns).
• Code is first-class: titled, copyable snippets close to every claim; a page that teaches a command shows the command before discussing it.
• Structured facts go in tables (arguments, options, defaults, error codes, limits), not prose.
• Callouts (note/tip) and step lists carry warnings and procedures (corpus anatomy).
• Every section heading is addressable by anchor (the evidence synthesis' conclusion: first success ends in a changed URL the reader can share).
• No "Boundaries" page or section (operator decision, 2026-08-19; the corpus never had one). Scope and security facts appear inline in the page they concern.
• Guides and reference cross-link (the most repeated practice in the study notes: "tutorial-to-reference pathways"). The shared layout renders prose as plain text today, so cross-references name the target page explicitly; inline links are a component change when needed.
• On-page table of contents for long pages — full-text crawl: "in this article"/TOC blocks are near-universal on reference giants' long entries, and our own reference pages exceed 8k characters routinely. Rule: a page with six or more h2 sections carries an in-page TOC right after the lede (DocumentationLayout component change, tracked with the corpus evidence).
• Branded title suffix — every major vendor titles pages " — documentation" (Grafana Labs, Elastic Docs, Firebase). Wisent rule: the <title> ends with "— documentation"; breadcrumbs stay unbranded.

4. Findability and versioning

• Lookup is the central docs journey (the evidence capture is first-answer journeys; 34/50 references expose inline or modal search). At the current Wisent scale the grouped sidebar is the lookup path; a site that outgrows sidebar scanning gains search as a component change, not a per-site hack.
• Every section is addressable — anchored headings (DocumentationLayout ≥0.4.0).
• Code is copyable — a Copy button on every code block (≥0.4.0; corpus quick-start behavior).
• Docs state the exact version they describe (five references carry version selectors; 14 study notes emphasize versioned behavior) and are re-verified on version bumps. One current version, stated honestly; multi-version publishing is not prescribed.

5. Sourcing and honesty

• Content comes from the product's README, code, and observed behavior — never invented. No stable public binary → the docs say so and show the source path that works today.
• Every claim is demonstrable: exact commands, exact paths, exact states.
• Docs change in the same change that alters the documented contract.
• Reference is checked against the surface it documents, mechanically. The corpus gated CI on a three-way CLI-docs drift checker (wisent-landing-new@d0cff21, parser vs dispatch vs docs, extended to arguments and the Python API in b59e65d). Each docs site names its drift check; "none exists yet" is a recorded gap, not a default.
• Documentation is a Wisent surface: behavioral verification goes through Probierz like every other surface (landing-page rubric precedent; a docs rubric does not exist yet — named gap, not invented rule).

6. Prohibited patterns and completion gate

Prohibited patterns

• A second docs shell, palette, or section anatomy beside DocumentationLayout.
• A product-specific, recolored, or hand-maintained favicon beside the canonical landing-cli/assets/favicon.svg.
• A "Boundaries" page or section, under that name or any euphemism ("What X does not do", "What integrations must not expect").
• Invented content: an FAQ, roadmap, or issue list without sourced material behind every entry.
• Reference claims verified against nothing — a flag, key, or route that no binary, config file, or source file was checked for.
• Copying a product's docs content into the portal or into another product's site.
• A structural rule added to these guidelines without a named source — how the first version of this file failed.

Completion gate

Documentation for a product is complete when:

• the site renders the shared layout and states the exact product version its claims were verified against;
• its landing page serves the canonical Wisent favicon emitted by landing-cli, with no product-local favicon source;
• every surface the product exposes has its reference: commands iff a CLI exists, machine API iff an HTTP/programmatic surface exists, configuration iff config keys exist, SDKs iff they ship, concepts for the contracts those surfaces rest on;
• a reader can reach one real result from Quick start alone, with paste-ready commands;
• the truth-over-time kinds that apply exist: changelog for a versioned product, migration guides once a breaking change shipped, limits with their numbers, troubleshooting from observed failures;
• every claim traces to the product's README, code, or observed behavior, and the reference has a named drift check or a recorded gap;
• the tail ends with support (community channel and operator contact);
• the portal entry reflects reality ("Dedicated site" only when the site exists and serves).

7. What is deliberately not prescribed

Page counts and section counts, dark mode (0/50), breadcrumb depth (0/50), code-language tabs (1/50), persistent multi-product switchers (1/50), "related resources" rails (1/50), interactive playgrounds (10/50 carry one but the corpus never did — a candidate, not a rule). Language selectors: the journey set showed none, but the full-text crawl contradicts that for giants — Datadog serves full mirrors under /ja, /fr, /es, /pt-br, /ko — so treat localization as a real pattern at scale and a deliberate non-goal at Wisent's current size. Each remaining item appears rarely enough in the sources that prescribing it would be invention.