# Public Docs Guide (Doxygen-Friendly)

Purpose: keep `docs/public` readable, accurate, and exportable via Doxygen.

## Authoring checklist
- One H1 per page; keep openings short (2–3 lines) and outcome-focused.
- Lead with “who/what/why” and a minimal quick-start or TL;DR when relevant.
- Prefer short sections and bullet lists over walls of text; keep code blocks minimal and copy-pastable.
- Use relative links within `docs/public`; point to `docs/internal` only when the public doc would otherwise be incomplete.
- Label platform-specific steps explicitly (macOS/Linux/Windows) and validate against current `CMakePresets.json`.
- Avoid agent-only workflow details; those belong in `docs/internal`.

## Doxygen structure
- `docs/public/index.md` serves as the `@mainpage` with concise navigation.
- Keep headings shallow (H1–H3) so Doxygen generates clean TOCs.
- Include a short “New here?” or quick-start block on entry pages to aid scanning.

## Accuracy cadence
- Re-verify build commands and presets after CMake or CI changes.
- Review public docs at least once per release cycle; archive or rewrite stale guidance instead of adding new pages.

## Naming & formatting
- Use kebab-case filenames; reserve ALL-CAPS for anchors like README/CONTRIBUTING/AGENTS/GEMINI/CLAUDE.
- Prefer present tense, active voice, and consistent terminology (e.g., “yaze”, “z3ed”, “preset”).

## When to add vs. link
- Add a new public page only if it benefits external readers; otherwise, link to the relevant internal doc.
- For experimental or rapidly changing features, keep the source in `docs/internal` and expose a short, stable summary here.