29 lines
1.6 KiB
Markdown
29 lines
1.6 KiB
Markdown
# 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.
|