# Project Docs Authoring

> Mandatory rules when creating or editing consumer wiki documentation under docs/, including the verified-examples contract, marker grammar, placeholder paths, and validation commands.

- Skill: `netdata/project-docs-authoring` (Agent Skill)
- Install (CLI): `npx skillmds@latest add netdata/project-docs-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/netdata/project-docs-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: netdata (https://skillmd.com/u/netdata)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/netdata/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.