# Docs Author

> Plans, writes, or restructures project documentation - Diátaxis structure (tutorials, how-to guides, reference, explanation), minimal doc set, runnable examples, README-to-docs graduation, drift prevention. Use when the user asks to write, improve, or reorganize docs, guides, or tutorials. Not for the README itself, deploying a docs site, or community files.

- Skill: `paldom/docs-author` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add paldom/docs-author`
- Raw SKILL.md: https://api.skillmd.com/api/skills/paldom/docs-author/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: Paldom (https://skillmd.com/u/paldom)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/paldom/docs-author

---


# docs-author

Produces a documentation set users can actually learn from. Default model
output fails at this in predictable ways — blended tutorial-reference hybrid
pages, navigation shaped like the module tree instead of user tasks, invented
code examples, and four empty "Tutorials/How-to/Reference/Explanation"
folders scaffolded as if structure were progress. This skill exists to
prevent exactly those failures.

## When NOT to use

- The README file itself → `readme-author`. Boundary: README = the front
  door; everything past it = this skill. "Turn our 800-line README into
  docs" uses this skill for the content and hands the README slimming to
  `readme-author`.
- Standing up, deploying, or fixing the docs *site* (generator, GitHub
  Pages, CI pipeline) → `docs-site`. The two compose: content here,
  pipeline there.
- CONTRIBUTING, SECURITY, CODE_OF_CONDUCT and other community files →
  `community-health`.
- Docstrings or inline code comments in source files → ordinary editing.

## Workflow

1. **Inspect before writing.** Read the repo: public API surface, existing
   README/docs/wiki, open issues and support questions (they reveal the
   missing how-tos). Classify every existing docs chunk by mode — tutorial /
   how-to / reference / explanation — before writing anything new. The
   framework's own author's rule: improve one page at a time and publish
   each step; never scaffold four empty sections.
2. **Scope the minimal viable set** (see `references/docs-playbook.md`):
   getting-started tutorial, how-tos for the top real tasks, generated
   reference, 1–3 concept pages, troubleshooting by symptom. Scale down for
   small projects — no empty or "coming soon" pages, ever. Below the
   navigational-need threshold, a good README is the whole answer.
3. **Structure task-first.** Navigation named by user tasks and topics
   (`authentication.md`), never by code modules; at most two levels deep;
   every page reachable from the index. Move content out of the README,
   don't copy it — duplicated content always forks. (`README.md` itself
   stays at the repo root for registry display.)
4. **Write each page in exactly one mode**, using the per-mode recipes and
   style rules in the playbook: second person, imperative, present tense,
   conditions before instructions, scannable structure, short sentences
   (~25-word check), no "simply/just/please", emphasis under ~10%.
   A sentence of inline explanation is fine; sustained explanation gets its
   own page and a link. After drafting, a `/slop-lint` + `/deslop` pass
   (paldom/noslop, when installed) strips AI-writing tells from docs prose.
5. **Make every example runnable.** Complete as pasted (imports, setup,
   expected output), verified against the actual source in this repo —
   never written from memory. Label anything partial. Apply the
   clean-machine test to install/quickstart steps; wire doctest/CI example
   tests where the ecosystem supports them.
6. **Never hand-write what a tool can generate.** API reference comes from
   docstrings/types/OpenAPI (generation wiring belongs to `docs-site`);
   hand-write only what has no source of truth to generate from.
7. **Drift pass.** When syncing docs after code changes: search the whole
   docs tree for renamed/removed identifiers, not just the obvious page;
   mark deprecated-but-working features with their replacement instead of
   deleting; keep phrasing version-agnostic. Recommend the process fix —
   docs updated in the same PR as user-facing changes, enforced by a PR
   checkbox.
8. **Lint.** Run and fix errors, triage warnings:
   ```bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/docs_lint.py" docs
   ```
9. **Present the result**: the doc tree, what each page is (its mode), what
   was deliberately left out, and the signal that should trigger adding it.

## Output spec

Every page classified in exactly one Diátaxis mode; navigation task-shaped,
≤2 levels, no orphans; examples complete, runnable, and verified against the
repo; reference generated, not hand-written; README depth moved (not copied)
into docs; `docs_lint.py` exits 0.

## Gotchas

- The default LLM genre is the blended "guide" — classify the page's mode
  *before* writing it, not after.
- Docs are anti-DRY where repetition saves the reader a hunt between pages —
  but README↔docs duplication always drifts; link or include instead.
- An auto-generated API dump is not documentation — reference feeds the set;
  tutorials and how-tos are what drive adoption.
- FAQs fragment and rot; fold answers into findable pages and keep
  troubleshooting organized by symptom/error string.
- Coding agents are now a large, silent docs audience (they never file
  issues) — self-contained sections and text-over-screenshots serve them
  and human skimmers alike (playbook has the rules).
- Wrong docs are worse than no docs: when a fact can't be verified against
  the code, cut it or mark it unverified — never guess.

## Files

- `references/docs-playbook.md` — Diátaxis application, minimal doc set,
  per-mode page recipes, style rules, examples policy, drift prevention,
  contested points.
- `scripts/docs_lint.py` — deterministic tree lint: broken relative links,
  missing index, orphans, nesting depth, filename style, heading structure,
  emphasis budget; non-zero exit on errors.