docs-writing

Documentation Writing

• IS: writing and auditing technical documentation quality (Diataxis doc types, voice, structure, clarity, runnable code, formatting, navigation, content hygiene, agent-readable docs) 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 or a whole-README rewrite (use readme-creator; a README that needs its prose fixed in place stays here), AGENTS.md or CLAUDE.md instructions (use agents-md), marketing and landing-page copy (use copywriting), or the product's own error strings and CLI output (use dx-audit; this skill covers the docs that describe them).

Mode dispatch

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

Classify before anything else

Doc type gates which rules apply, so classify every file first. Use the Diataxis compass: does the page serve action (doing) or cognition (understanding), and is the reader acquiring a skill or applying one?

A page that answers differently for different sections is mixed; structure-diataxis handles the split. Classify by the reader's task, not the filename. A README can orient or reference; a getting-started page can be a tutorial or a goal-directed how-to.

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 with the compass; name the audience
- [ ] Step 3: Run CRITICAL categories (voice-, structure-), skipping rules the type-gating table excludes
- [ ] 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

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 with the compass; name the audience and what they can do afterwards
- [ ] Step 2: Read the defaults bundles (voice-defaults, clarity-defaults, scan-defaults) plus the structure- and code- rules the type-gating table keeps
- [ ] Step 3: Draft: bottom line up front, quick start for getting-started docs, runnable example per concept, next steps for tutorials and how-tos
- [ ] Step 4: Apply the type-relevant rules to concrete weaknesses in the draft
- [ ] Step 5: Verify: run every example, resolve every link, confirm parameter names and defaults against the implementation; quote the command output

Step 5 is the exit criterion: a doc ships when its examples ran and its links resolved, not when it "reads well". Length follows what the reader has to do, not the template: drop a section the page does not need rather than filling it.

Type-gating table

These rules apply only to the listed types. Flagging them elsewhere tells the author to break Diataxis.

Everything else applies to every type. Tutorials additionally get the we allowance in voice-defaults; reference pages get the signature-block allowance in structure-heading-overview.

Rule categories by priority

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. A missing quick start on an explanation page, or a "Next steps" section demanded of a reference page, is a finding against Diataxis, not for it. Check the type-gating table before reporting.
• 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.
• Load rule files by prefix for in-scope categories only. Loading the whole folder before scope is known floods context and buries the CRITICAL findings under MEDIUM ones.
• "Should" is not a bug. Google's current word list uses "should" for a recommendation and "must" for a requirement; flag "should" only where the sentence states a requirement. Flagging every "should" produces a wall of false positives.
• An example key that looks live (sk_live_...) gets pasted into real code and tripped by secret scanners. Sample credentials use the provider's test prefix (sk_test_...) or an explained placeholder (YOUR_API_KEY); see code-placeholders.
• A hand-typed "Last updated: 2024-03-01" that nobody maintains reads as "abandoned" and is worse than no date. Only recommend hygiene-update-metadata when the date can come from the build or VCS.
• A "This guide is part of the X series" opener on every page of a docs site duplicates the sidebar and breadcrumb the site already renders. nav-breadcrumb-context is for plain Markdown in a repo and for pages with a prerequisite the reader must have met.
• Don't rewrite content you were asked to review; report and propose fixes unless the user said "improve" or "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 or a full rewrite; this skill audits and fixes existing ones in place.
• agents-md: AGENTS.md/CLAUDE.md instruction files (execution-first, not reader-facing docs).
• copywriting: marketing, landing-page, and product copy.
• dx-audit: the product's own error messages, CLI output, and API ergonomics; this skill covers how the docs describe them.
• optimise-seo: implementing llms.txt, AI-crawler policy, and Markdown routes in a Next.js App Router site; nav-agent-readable says what the docs should expose, that skill builds it.
• 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.

Maintenance only: evals/evals.json contains regression scenarios for changes to this skill; it does not load during a user task.