project-docs-authoring

# Project Docs Authoring ## Purpose Keep the consumer wiki (`docs/`) decision-oriented, honest, and machine verified: every Rust and Go code example is compiled and executed in CI, so examples are contracts, not illustrations. ## Scope Use this skill when: - creating or editing any page under `docs/`; - adding, changing, or removing code examples; - changing `tests/docs/check_wiki_docs.py` or `tests/docs/verify_examples.py`; - changing `.github/workflows/wiki.yml` or `.github/workflows/docs-examples.yml`. Do not use this skill for `documentation/` (internal notes, not published). ## Mandatory Knowledge - `docs/` is the published GitHub wiki source (SOW-0100). Internal links use `[[Page-Name|Label]]`; internal `*.md` Markdown links are rejected by the validator. - Every fenced `rust` or `go` block in `docs/` must be immediately preceded by an HTML-comment marker: either `<!-- verify-example: lang=<rust|go> id=<unique-slug> -->` or `<!-- illustrative-only: <reason> -->`. Markers are invisible in the rendered wiki. - `verify-example` attributes: `lang` (required, must match the fence), `id` (required, `[a-z0-9-]+`, unique across all pages), `mode=run` (default, compile and execute) or `mode=build` (compile only), `fixture=basic` (default), `prelude=<name>` for fragments that continue from registered setup code in `tests/docs/verify_examples.py` (`PRELUDES`). - Examples must use only the documented placeholder paths, which the harness substitutes at run time (longest match first): `/var/log/journal/example/system.journal` (single-file fixture), `/var/log/journal` (directory fixture), `/var/log/journal-sdk` and `/var/log/journal-sdk/example.journal` (per-example scratch), `/tmp/example.journal` (scratch). - Rust examples are rustdoc-shaped: top-level `?` is allowed and hidden lines start with the `#` marker followed by one space (kept in compiled code, hidden in rendered docs); a final `# Ok::<(), Box<dyn std::error::Error>>(())` line marks Result-main wrapping. Go examples are function-body fragments that may `return err`; the harness wraps them in `func run() error`. - Examples must be standalone-compilable after wrapping: in Go, do not bind variables that are never used, and do not re-declare prelude variables with `:=` (use `if err := ...; err != nil` forms). - Fixtures are synthetic and deterministic, built by the harness with the in-repo Go SDK; never reference the host journal in examples, and never use real identities. - Local validation before push: `python3 tests/docs/check_wiki_docs.py` and `python3 tests/docs/verify_examples.py`. CI runs both (`.github/workflows/wiki.yml` validates and publishes; `.github/workflows/docs-examples.yml` compiles and runs examples). - When validation tooling runs `cargo`, `go`, or Python test scripts locally, export cache redirection (`CARGO_HOME`, `CARGO_TARGET_DIR`, `GOMODCACHE`, `GOCACHE` under repo-local `.local/` paths) per the orchestration skill cache rules. Python is used only as repository tooling here. - Wiki pages document marker syntax inside ```markdown fences (`docs/Wiki-Publishing.md`); the validator and harness are fence-aware and ignore marker text inside fenced blocks. Preserve that property when changing either tool. - Performance guidance honesty rule: `docs/Production-Profiles.md` names Rust and Go as the product throughput targets. Do not weaken that statement without benchmark evidence recorded in an active SOW. - The docs perception model: pages are organized around choosing an API surface (idiomatic SDK, facade, Explorer, Netdata function boundary, journalctl rewrite CLI, verifier). New content should answer "which surface and why" before "how". ## Workflow Checklist 1. Edit or add the page; keep wiki-style links. 2. Mark every Rust/Go fence (verify-example or illustrative-only with a reason). 3. Run both validators locally; iterate until green. 4. For new example shapes, extend the harness (preludes, fixtures, substitutions) within the active SOW, with unit tests. 5. Record docs changes in the active SOW. ## Evidence - `.agents/sow/done/SOW-0100-20260608-consumer-docs-github-wiki.md`: wiki structure, link rules, publishing. - `.agents/sow/done/SOW-0103-20260611-docs-api-perception-and-verified-examples.md`: verified-examples harness, marker grammar, fixtures, CI wiring. - `docs/Wiki-Publishing.md`: author-facing summary of the same rules. ## Update Rules Update this skill when: - the marker grammar, placeholder vocabulary, preludes, or fixtures change; - a new language gains verified-example support; - validation commands or CI workflows change.