Documentation governance

This page defines how Vox documentation is organized and how to keep it from drifting.

Authority map

Taxonomy

Folder placement communicates ownership. Frontmatter communicates how a page should appear in the book.

Category vocabulary

Use one of these category values in frontmatter:

Alias compatibility exists for a few legacy values, but new docs should use the canonical forms above.

Status vocabulary

Use status when the distinction matters to readers:

Do not use status to make aspirational pages sound shipped.

Frontmatter starter template

Use this template for new pages so docs lint passes on first run:

---
title: "Page title"
description: "One specific sentence about what this page covers."
category: "architecture"
status: "roadmap"
last_updated: 2026-04-06
training_eligible: true
---

Fast local lint loop:

• cargo run -p vox-doc-pipeline -- --lint-only --paths architecture/my-page.md
• cargo run -p vox-doc-pipeline -- --lint-only --paths architecture/my-page.md --fix

Authoring guardrail:

• Do not start a line with a single backtick in prose (for example `vox ... at line start). Use normal prose with inline code or a full triple-backtick fence.

Authority tiers (A-D)

Use one authority tier per documentation domain. The canonical registry is contracts/documentation/canonical-map.v1.yaml.

Rules:

• Do not label a page as "SSOT" unless it is the sole B-canon page for its domain id in the canonical map.
• D-index pages should summarize links only. If behavior text duplicates a B-canon page, remove it.

Placement guide

When adding or moving a page:

1. If the source of truth is machine-readable, put the contract in contracts/ and link to it from docs/src/reference/.
2. Register the domain in contracts/documentation/canonical-map.v1.yaml with spec_paths, one canon_doc, and any alias stubs.
3. If the subject is a communication protocol or transport boundary, make the machine-readable artifact discoverable from contracts/index.yaml and mirror it from one canonical docs/src/reference/ page.
4. If the page teaches or explains the user-facing language, keep it in docs/src/.
5. If the page is mainly for contributors or automation, prefer docs/src/contributors/ or docs/agents/.
6. If the page is research or planning, keep it under docs/src/architecture/ and label it clearly with status: research or status: roadmap.
7. If a page exists only as a compatibility stub, make it a short redirect and avoid duplicating the canonical content.

Claim policy

Forward-facing docs should describe the architecture that exists now.

Prefer:

• "Vox documents a compiler pipeline that generates Rust and TypeScript artifacts."
• "Mens currently defaults to code-oriented training lanes."
• "This page is research, not a claim that the capability is fully shipped."

Avoid:

• "Vox already does everything in this section automatically" unless the code path is current and documented.
• "Mens answers architecture questions" unless that retrieval or QA path is explicitly wired and tested.
• "SSOT" in titles when the page is only a convenience summary, pointer, or index.

Maintenance protocol

Use this lightweight review matrix for high-drift surfaces:

Review cadence

• Front door surfaces: review on every material product-language or contributor-experience change.
• Architecture and reference pages: review when the owning code path changes.
• Research and roadmap pages: keep their status current even if the implementation does not move.
• Contributor and governance pages: review whenever CI, inventory rules, or workflow expectations change.

Related

• Contributor hub
• Doc-to-code acceptance checklist
• Architectural governance (TOESTUB)
• Doc inventory verifier

Documentation Update Checklist

Before committing documentation to the repository, verify the following constraints:

1. Syntax correctness: Code snippets must parse cleanly under current validation. Prefer {{#include}} from examples/golden/ where policy requires it. Machine-checked layout lives in examples/examples.ssot.v1.yaml (mdbook_includes_resolve_to_existing_golden_vox in vox-compiler tests).
2. Authority registration: New canonical pages must be reflected in contracts/documentation/canonical-map.v1.yaml; aliases must remain link-only.
3. Status marker: Use status only when needed (current, experimental, legacy, research, roadmap, deprecated).
4. Terminology: Use established nomenclature (Codex vs Arca, Mens vs Populi, Islands vs Components).
5. Navigation integrity: If creating a user-facing document, verify SUMMARY.md is updated and passes vox-doc-pipeline --check.