Generates tutorials, how-to guides, getting-started content, and API references using the Doc Writer persona — example-first, progressive disclosure, copy-paste ready. Use when writing docs for end users, creating a guide or tutorial, documenting a stable feature, writing API references, or for docs-driven development.
Announce at start: "I'm using the writing-end-user-docs skill with the Doc Writer persona."
| Aspect | Guidance |
|---|---|
| Persona | Doc Writer (${CLAUDE_PLUGIN_ROOT}/personas/doc-writer.md) |
| Output location | Project-specific — typically docs/ or a documentation site directory |
| Structure | Progressive disclosure: getting started → common tasks → advanced → internals |
| Readability target | Flesch-Kincaid grade ≤ 8 (initial estimate — calibrate against real docs) |
| Core principle | Show a working example first, explain after |
Frame the document around a task: "How do I check a handoff's token count?" — not "The tokens subcommand of bito."
Load the Doc Writer persona from ${CLAUDE_PLUGIN_ROOT}/personas/doc-writer.md.
Dialect: Check for BITO_DIALECT environment variable or the project's bito config for a dialect preference (en-us, en-gb, en-ca, en-au). If set, use that dialect's spelling conventions consistently throughout the draft. If not set, default to en-US.
The Doc Writer's defining principle: example first, explanation second. Every section leads with a runnable example; the prose is connective tissue.
| Type | When | Structure |
|---|---|---|
| Getting started | First-time users | Install → first command → expected output → what just happened |
| Tutorial | Learning a workflow | Goal → prerequisites → step-by-step with expected output at each step → next steps |
| Guide | Common tasks | Brief context → recipe → variations → gotchas |
| API reference | Looking up specifics | Signature → one-sentence description → example → parameters → return value → errors |
Each level should feel complete on its own:
Every claim about what the tool does must include a runnable example. The examples are the documentation — the prose around them is connective tissue.
For CLI tools:
bito tokens .handoffs/2026-02-08-my-handoff.md --budget 2000
# PASS — 1,847 tokens (budget: 2,000)
For config-driven checks:
bito lint record/decisions/0001-my-adr.md
# Runs completeness + readability checks from .bito.yaml rules
Before saving, verify:
Run through editorial-review if available. The Doc Writer voice should be consistent: accessible, example-first, respectful of the reader's time. Check specifically that the document doesn't slip into the Technical Writer voice (too opinionated, too many trade-offs) or the Marketing Copywriter voice (too benefit-forward, not enough substance).
writing-design-docs provides the architectural context that informs what to document. Brainstorming sessions may identify user-facing features that need docs.editorial-review validates the finished document. writing-changelogs (release announcements) may link to these docs.| Mistake | Fix |
|---|---|
| Leading with architecture or history | First code block within 10 lines. Lead with what the user can do. |
| "Simply" or "just" before multi-step process | Drop the word. If it's more than one action, it isn't simple. |
| API docs without usage examples | Every function/command needs a runnable example, not just parameter descriptions. |
| Front-loading caveats | Happy path first. Caveats after the reader succeeds. |
| Assuming reader has read other docs | Stand alone or link explicitly. No "as described elsewhere." |