---
name: SOLNIX-HANDBOOK-WRITER
description: Write Solnix documentation (handbook chapters, man-page prose, news) in the project's voice. Use when drafting or editing docs so they match the honesty-first, illumos-literate Solnix style and brand rules.
---

# Writing for Solnix

Documentation is a first-class contribution. Match the project's voice and rules.

## Voice

Plain, technical, honest. Explain the illumos concept, then the Solnix mechanism.
Prefer a translation table (from Linux/BSD/macOS/Windows) over abstract prose —
most readers arrive from somewhere else. See
[voice](community/steering/voice.md).

## Honesty is non-negotiable

Never describe planned work as done. A chapter may say "planned" or
"dev-preview" — it may not imply a feature works when it doesn't. The COSMIC
desktop *compiles*; it is not GPU-driven display yet — so docs say exactly that.
See [honesty-over-hype](community/steering/honesty-over-hype.md).

## Brand

- **"Solnix"** is a proper noun — **capitalized** in prose (including
  sentence-initial, mid-sentence, titles).
- **lowercase `solnix`** only in code contexts: domains (`solnix.io`), commands
  (`solnix-rebuild`), identifiers, store paths, repo/package names
  (`solnix-pkgs`), slugs, inline code, link targets.
- `illumos` and `nixpkgs` are always lowercase; `Nix`/`NixOS` are capitalized.
- The styled logo wordmark (split `sol`/`nix`) stays lowercase.

See `site/STYLE.md` for the full rule; CI enforces it (`qa/check-content.sh`).

## Mechanics

- Handbook chapters live in `site/handbook/src/*.md` (mdBook). URLs are clean
  (extensionless); `.html` 301s.
- Use `##`/`###` headings — the handbook indexer sections on them so each heading
  becomes a deep-linkable, searchable unit (`/handbook/<chapter>#<anchor>`).
- Link first mentions of external terms to their canonical reference.

## Workflow

See [write-a-handbook-chapter](generic/workflows/write-a-handbook-chapter.md).