Documentation guidelines

The rules this documentation set follows, stated as norms — a checklist for anyone, human or otherwise, writing or reviewing a page here. See Engineering guidelines for the equivalent conventions covering code.

Format

  • reStructuredText only — no Markdown, no MyST, anywhere under doc/.

  • Documentation lives in doc/ (singular), and is built by zdocs itself through the same registry and the same CMake surface any consumer uses.

  • Every page is reachable from a toctree. No orphan pages, no dangling references.

  • The gate is the engine’s own doc-check target plus a clean stage-two build log — not sphinx-build -W, which the two-stage build’s deliberate stage-one warnings would fight. See 0011. Documentation structure: Diátaxis, arc42-lite, and two documents.

Structure

Every page lives in one of the four Diátaxis quadrants, decided before writing rather than after:

  • Tutorial — learning by doing: a guided path to a working result.

  • How-to guide — a task recipe for someone who already knows their way around.

  • Reference — facts to look up: precise, complete, no narrative.

  • Explanation — understanding: why something is built the way it is.

Two documents

The manual holds the Diátaxis tree; the companion API document holds generated reference. The line between them is the kind of reference, not the subject:

  • Task-facing reference belongs to the manual — the ZDOCS_* contract, the registry schema, the directives an author writes, the command-line tools. A reader consults these to use zdocs.

  • Implementation reference belongs to the API document — module and command signatures, extracted from docstrings and from the CMake sources themselves. A reader consults these to change zdocs.

Nothing is written in both. A manual page needing a signature links to it.

Architecture pages

The architecture record is an arc42-lite page set under explanation/architecture/: introduction and goals, system context, solution strategy, building blocks, cross-cutting concepts — one page each. System context and building blocks each carry a C4-style diagram rendered from source with .. graphviz:: (context = level 1, building blocks = level 2), so diagrams stay text-diffable and cannot rot into out-of-date screenshots.

Facts only

Architecture pages state what is, in present tense. Rationale, history, alternatives considered and provenance live in Decisions, not in the architecture prose. There is no “what this is not” section: a deferral worth recording becomes one positive clause, or a line in the relevant ADR, never a standalone negative-space essay.

Honesty about maturity

  • Anything not yet implemented is explicitly hedged as a design target — say so on the page; do not let present-tense prose imply otherwise.

  • Never promise a page or a feature that does not exist. Link only to what is actually written.

  • A known defect, a parked decision or a deliberate piece of debt is worth documenting where a reader would trip over it. Documenting a rough edge is not an admission; hiding it is how a reader loses a day.

Vocabulary

  • The glossary owns nuanced terminology. Define a term once, in Glossary, and never restate that definition elsewhere. Use :term: where a reader meeting the word needs the definition to follow the sentence — typically its first use on a page aimed at newcomers. Reference and explanation pages written for a reader already fluent in the vocabulary do not need to link every occurrence; linking everything is as unreadable as linking nothing.

  • Write for a developer who knows CMake and Zephyr but has never built a multi-document, multi-toolchain documentation set. Sphinx and Doxygen concepts get named and explained; embedded concepts do not.

  • Distinguish the engine’s vocabulary from a consumer’s throughout. Type and link names in examples are the consumer’s, and an example that silently uses the engine’s defaults teaches the wrong lesson.

ADRs

Architecture decisions are numbered rST files under explanation/decisions/, each with Status, Context, Decision and Consequences sections. To record one: copy the most recent, take the next sequential number, and ship it in the same change that implements the decision — not as a documentation-only change afterwards. ADRs are immutable records of a decision made at a point in time: a later change that revisits a decision supersedes it with a new ADR rather than rewriting the old one.