Writing clear docs with AI

Agents are useful for docs when the curriculum is on demand and the house voice stays thin and durable.

Split the load

Keep always-on (rules / STYLE) Put in Cursor skills / optional layers

Titles stance, Diátaxis shape, AsciiDoc checklists, Nieman anti-terse tips

Mode-split body packs (news vs blog), long anti-slop rubrics, connector loops

Site STYLE.adoc / AGENTS.md

skills/<name>/ via Bootstrap Cursor skills
Framing for studio setup

Vibe coding bootstrap

Practical loop

  1. Point the agent at the component docs/ tree and the site STYLE before drafting.

  2. Name the channel: news (outward shared record) vs blog/essay (inward idea) vs changelog (shipping minutiae).

  3. For News/blog narrative, apply the Nieman scene checklist in agent-rules general/documentation.md (camera angle, scene vs summary, pace, time cues, pull-forward endings).

  4. Prefer short always-on rules; load heavy voice packs only when drafting that genre.

  5. Verify links, nav, and changelog entries the same way you would for hand-written docs.

Anti-patterns

  • Pasting a full style guide into User Rules (context bloat every chat)

  • Telegraphic bullet-essays on the narrative channel

  • Inventing facts, quotes, or “everyone knows” filler

  • Publishing a second Antora site for one page—wire into the org hub instead (Where docs live)

Related