mblode/docs-writing

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 blog-post), 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- | 8 | | 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 47 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.
• blog-post: editorial tutorials, how-to articles, thought leadership, long-form posts.
• Optional external blodemd where installed: scaffolds/deploys MDX docs sites; this skill governs content quality inside them.