role-technical-writer

Provides: Audience identification, document type selection, drafting order, and review stance for documentation work.

Quick Reference

Goal: make the next reader action obvious

Principles: audience first, examples over abstraction, accurate over comprehensive

Never: create a new summary or planning file unless the user asked for one

Reference: skill:standards-documentation for structure and skill:standards-markdown for formatting

Workflow

1. Identify the audience

Each audience needs different content, and a document that serves all four usually serves none:

2. Choose the document type

• README: orientation and quick start.
• Guide: a task-based procedure.
• API docs: contract, examples, errors, compatibility.
• Spec or ADR: context, decision, alternatives, consequences.
• Migration notes: what changed, action required, rollback or fallback.

Read the documentation type patterns when creating a README, API reference, code comment policy, architecture document, or procedural user guide. Load only the section for the artifact requested.

3. Draft the minimum useful content

• Start from the reader's goal, not the system's structure.
• Use concrete examples and show expected output.
• Link to detail instead of embedding unrelated background.

4. Review

Check accuracy against the code and config before polishing prose. Verifying a command is worth more than improving a sentence. Then remove stale, redundant, or generic content.

Documentation Layout

Scale the structure to the project. A single accurate README.md beats a docs/ tree of stubs.

Small project:

README.md          # Overview, quick start, installation
API.md             # API reference
CONTRIBUTING.md    # How to contribute

Large project:

docs/
  README.md              # Documentation home
  getting-started/       # Installation, quick start
  guides/                # Task-based procedures
  reference/             # API and configuration
  decisions/             # ADRs

Split a document only when readers with different goals keep colliding in it.

Gotchas

• Do not create new summary files unless the user asks. Keep the summary in the conversation and update the existing docs instead.
• Do not document obvious code behavior. Document decisions and non-obvious constraints.
• Do not let formatting work expand the scope of the requested change. Reformatting untouched sections buries the actual edit in diff noise.
• Do not describe planned behavior as current. Mark anything unverified.

Checklist

Before finishing documentation work:

• The target audience and the reader's next action are clear
• Examples, commands, links, and paths are accurate, or caveated as unverified
• The document is as short as its use case allows
• Markdown renders cleanly and code fences are balanced
• Stale or superseded content was removed, not just added around
• No new summary or planning file was created unless requested
• Formatting changes stayed within the requested scope

When the change documents a new or altered feature, also check the documents that sit outside the one you edited:

• README quick start, if the feature changes how someone gets started
• API reference, for new or changed endpoints and functions
• User guide, for how to actually use it
• Architecture docs, if the feature changes how the system fits together
• Changelog entry
• Migration note, if anything breaks for existing users

Integration with Other Skills

With standards-documentation: apply the skeleton and content conventions for the chosen type.

With standards-markdown: apply the formatting rules, including the SKILL.md carve-out.

With standards-api-design: document a public or partner contract accurately.

With role-product-engineer: turn a shipped feature into release notes and user-facing docs.