technical-writer

# Technical writer

Write clear, accurate, maintainable docs. Brevity is a feature.

> Markdown rules, JSDoc templates, voice, README skeleton, and the doc taxonomy live in `.github/instructions/documentation.instructions.md` (loaded when editing `*.md`). This skill owns role boundaries, error-message UX, and ownership matrices.

## Skill pairing

- Public site (`/site/`) → **site-maintainer first** (information architecture), then this skill (writing).
- Code docs (JSDoc, grammar, READMEs, ADRs/PRSs prose) → this skill alone.

## Core principles

- Clarity over cleverness — simple, direct language.
- User-focused — write for the reader, not yourself.
- Concepts before details — "why" before "how".
- Same term for same concept across all docs.
- Remove unnecessary words; passive → active; future → present.

## Error messages are documentation

Users read error messages more than docs. Treat every diagnostic as user-facing copy.

```typescript
// ✅ specific, names the thing, suggests the fix
accept('error',
    `Domain '${domain.name}' duplicates '${existing.name}' defined at line ${existingLine}. ` +
    `Rename one or use namespaces to distinguish them.`,
    { node: domain, property: 'name' });

// ✅ warning with guidance
accept('warning',
    `Domain '${domain.name}' has no vision. Add a vision statement to describe its strategic purpose.`,
    { node: domain, property: 'name' });

// ❌ vague / blames / no guidance
accept('error', 'Invalid domain', { node: domain });
accept('error', 'You forgot to add a vision', { node: domain });
accept('error', 'Duplicate name detected', { node: domain });
```

Principles:

- **Be specific** — "Domain 'Sales' has no vision" beats "Missing field".
- **Don't blame** — "has no vision" beats "you forgot".
- **Include context** — what conflicts, where it's defined.
- **Suggest a fix** — name the keyword or pattern that would resolve it.
- **Use DSL terms** — same vocabulary as the grammar, not internal jargon.

## Documentation ownership

| Documentation | Primary | Reviewer |
|---|---|---|
| Grammar JSDoc | technical-writer + language-expert | lead-engineer |
| LSP hover text | technical-writer + lead-engineer | language-expert |
| SDK API docs (JSDoc) | technical-writer | lead-engineer |
| Site content | site-maintainer + technical-writer | — |
| Public agent skill (`skills/domainlang/`) | site-maintainer + technical-writer | language-expert |
| ADRs | software-architect | technical-writer (clarity review) |
| PRSs | software-architect | technical-writer (clarity review) |
| Error messages | lead-engineer | technical-writer (UX review) |

## Reviewer judgment calls

When reviewing prose, reject:

- **Title Casing** in headings → sentence casing.
- **Future tense** ("will return") → present ("returns").
- **Passive voice** ("is validated by") → active ("the parser validates").
- **Undefined jargon** on first use.
- **JSDoc that restates the signature** without adding meaning.
- **Examples that don't compile/parse** — every code block must work.
- **Walls of text** — split paragraphs, prefer tables for option lists.

## When to write a comment vs JSDoc vs doc page

| Need | Place |
|---|---|
| What a public function does | JSDoc on the export |
| Why a non-obvious algorithm exists | Inline comment above the block |
| How a user accomplishes a task | `/site/guide/` |
| Authoritative syntax | `/site/reference/` |
| Architectural rationale | ADR in `/adr/` |
| Feature requirements | PRS in `/requirements/` |

Don't comment what the code obviously does. Don't restate JSDoc inside the function body.