docs-writing

name

docs-writing

description

Writes and audits technical documentation using the Diataxis framework and Stripe-style clarity. 48 rules across 9 categories covering voice, structure, clarity, code examples, formatting, navigation, scanability, content hygiene, and review. Use when writing docs, documenting APIs, writing documentation-site tutorials or how-to guides, auditing an existing README or docs site, or asking "review my docs", "improve this documentation", or "write docs for this". For editorial blog tutorials use the external ghostwriter skill with platform blog; for creating a README from scratch use readme-creator; for AGENTS.md or CLAUDE.md files use agents-md; for marketing copy use copywriting.

Documentation Writing

• IS: writing and auditing technical documentation quality (Diataxis doc types, voice, structure, clarity, runnable code, formatting, navigation, content hygiene) for docs sites, API references, documentation-site tutorials, how-to docs, and existing READMEs.
• IS NOT: editorial blog tutorials or articles (use the external ghostwriter skill with platform blog), a README from scratch (use readme-creator), AGENTS.md or CLAUDE.md instructions (use agents-md), or marketing and landing-page copy (use copywriting).

Mode dispatch

• Reviewing docs? → Audit workflow.
• Writing/rewriting a page? → Writing workflow.
• "Improve"/"fix" docs? → Audit first, then apply fixes yourself.

Audit workflow

Track this checklist:

Docs audit progress:
- [ ] Step 1: Scope to changed files unless a full sweep was requested
- [ ] Step 2: Classify each doc (tutorial, how-to, reference, explanation) and audience
- [ ] Step 3: Run CRITICAL categories (voice-, structure-)
- [ ] Step 4: Run HIGH categories (clarity-, code-)
- [ ] Step 5: Run remaining in-scope categories (format-, nav-, scan-, hygiene-, review-)
- [ ] Step 6: Report per the output contract, by severity

Doc type gates which rules apply, so classify before loading. Load rule files by category prefix (rules/voice-*.md, then rules/structure-*.md, ...) only for in-scope categories. After applying fixes, rerun the rules that produced findings before finalizing.

Writing workflow

Track this checklist:

Docs writing progress:
- [ ] Step 1: Pick one Diataxis type per file (tutorial, how-to, reference, explanation); name the audience
- [ ] Step 2: Read defaults bundles (voice-defaults, clarity-defaults, scan-defaults) plus structure rules for the type
- [ ] Step 3: Draft: bottom line up front, quick start for getting-started docs, runnable example per concept
- [ ] Step 4: Self-audit against CRITICAL and HIGH categories; fix findings
- [ ] Step 5: Verify: run every example, resolve every link, confirm parameter names against the implementation

Step 5 is the exit criterion: a doc ships only after its examples run and links resolve, not when it "reads well".

Rule categories by priority

Priority	Category	Impact	Prefix	Rules
1	Voice & Tone	CRITICAL	voice-	4
2	Structure & Organization	CRITICAL	structure-	9
3	Clarity & Language	HIGH	clarity-	5
4	Code Examples	HIGH	code-	7
5	Formatting & Syntax	MEDIUM-HIGH	format-	7
6	Navigation & Linking	MEDIUM-HIGH	nav-	6
7	Scanability & Readability	MEDIUM	scan-	2
8	Content Hygiene	MEDIUM	hygiene-	6
9	Review & Testing	LOW-MEDIUM	review-	2

For the full rule list per category, read rules/_sections.md. The *-defaults.md files (voice, clarity, scan, review) are multi-check bundles, 2-5 baseline checks each.

Output contract (audit mode)

## Documentation Audit Findings

### path/to/file.md
- [CRITICAL] `voice-defaults`: Passive voice obscures who performs the action.
  - Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

### path/to/clean-file.md
- ✓ pass

• Group by file; order by severity within each file.
• Use file:line when available.
• Every finding names the rule, states the issue, proposes a fix. No fix, not reportable.
• List clean files as ✓ pass so the author knows they were checked.

Gotchas

• Doc-type misclassification is the top false-positive source: structure-quick-start applies only to getting-started docs and READMEs, scan-three-column-api only to API references. Flagging a missing quick start on an explanation page tells the author to break Diataxis.
• Cite the specific failing check in a *-defaults.md bundle ("voice-defaults: passive voice"), not just the filename, or the author can't locate the issue.
• Don't load all 48 rule files up front; load by prefix for in-scope categories only, to avoid flooding context before scope is known.
• Don't rank MEDIUM/LOW polish above CRITICAL/HIGH; authors fix what they see first, so a serial-comma nit can bury a structure problem.
• Don't rewrite content you were asked to review; report and propose fixes unless the user said "improve/fix".
• Don't audit unchanged files unless a full sweep was explicitly requested; unscoped findings drown the real ones.

Related skills

• readme-creator: a README from scratch; this skill audits and improves existing ones.
• agents-md: AGENTS.md/CLAUDE.md instruction files (execution-first, not reader-facing docs).
• copywriting: marketing, landing-page, and product copy.
• Optional external ghostwriter where installed: editorial tutorials, how-to articles, thought leadership, and long-form posts, drafted from the blog platform profile.
• Optional external blodemd where installed: scaffolds/deploys MDX docs sites; this skill governs content quality inside them.