Writing User Docs
House style for user-facing documentation, voice, scope, structure, and what to leave...
Install
npx skills add callstackincubator/agent-skills --skill writing-user-docs -g -a claude-code -y- Repository
- callstackincubator/agent-skills1.7k
- Category
- Writing
- Updated
- 27d ago
- License
- MIT
- Context cost
- Lightabout 999 tokens
- Runs scripts
- No, instructions only
What it does
House style for user-facing documentation, voice, scope, structure, and what to leave out. Use this skill whenever writing, editing, or reviewing anything a user reads to learn how to use a tool, help center articles, getting-started guides, tutorials, feature docs, README usage sections, in-app help, release notes, or FAQ entries. Trigger it even when the request is phrased plainly, "document this feature", "write docs for X", "explain this to users", "write a README for this library", "turn these notes into a guide", and even when no style guidelines are mentioned. Also use it to review existing docs for tone, bloat, or leaked implementation detail. Do not use it for internal engineering docs, architecture write-ups, RFCs, or code comments.
User-facing documentation
Write for the person using the tool, not the person who built it.
"User" means whoever uses the thing. For an app, that's an end user. For a library, it's the developer who installs it. Either way they are not implementing it, and the docs should reflect that.
Voice
Everyday English, the way you'd explain it to a colleague sitting next to you. Formality doesn't add authority, it just adds distance and words.
- Second person, active, present tense. "You tap Save," not "the Save button should be tapped" or "the user will then be able to save."
- Cut "just," "simply," "easy," "obviously." They add nothing when things work, and read as mockery when they don't.
- No marketing adjectives. "Powerful," "seamless," "robust," "intuitive", that's the author admiring the product. The reader is mid-task and doesn't care.
- One term per concept, matching the UI exactly. If the button says Workspace, the docs never say "project" or "team space." Varying your vocabulary is good prose and bad documentation, every synonym reads as a new concept.
Scope: what goes in
Include only what the reader needs to use the tool. The default is to leave things out.
Implementation details stay out. Not the database, the queue, the framework, the algorithm's name, the internal service, the refactor it took to ship. The test isn't "is this technical?", it's "will the reader be surprised, or make a wrong decision, without it?"
Observable behavior passes that test even when it sounds technical, and belongs in the docs: rate limits, offline behavior, what syncs and when, where files are stored, what happens on a conflict, what survives a reinstall. The machinery producing that behavior doesn't.
