# Workflow: write a handbook chapter

Goal: add or improve a handbook chapter so it's correct, in-voice, and
searchable.

1. **Find the file.** Chapters are `site/handbook/src/<slug>.md` (mdBook). Add new
   ones to `SUMMARY.md`.
2. **Write in the Solnix voice** (`steering/voice.md`): explain the illumos
   concept, then the Solnix mechanism; use a translation table from
   Linux/BSD/macOS/Windows where it helps.
3. **Be honest** (`steering/honesty-over-hype.md`): mark planned/dev-preview
   work as such; don't imply a feature works when it doesn't.
4. **Mind the brand** (`SOLNIX-HANDBOOK-WRITER.md`): "Solnix" capitalized in
   prose, `solnix` lowercase in code contexts. CI (`qa/check-content.sh`)
   enforces it.
5. **Structure for search.** Use `##`/`###` headings — the handbook indexer
   sections on them, so each heading becomes a deep-linkable, BM25-searchable
   unit at `/handbook/<slug>#<anchor>`. Keep sections self-contained.
6. **Link first mentions** of external terms to their canonical references.
7. **Send the patch** to `hackers@` (signed). Doc patches are first-class.
8. **After deploy**, the indexer re-reads the chapter and the new/edited sections
   become searchable via `search_handbook`, `GET /api/v1/handbook/search`, and
   GraphQL `handbookSearch` within the deploy's indexing run.