documentation-writer

name

documentation-writer

description

Use when writing, updating, editing, rewriting, reviewing, or improving user-facing documentation, including README files, CHANGELOGs, release notes, setup or install guides, API references, onboarding docs, contributing guides, and similar prose meant to help someone understand or use a project. Trigger on requests like "update the docs", "rewrite the README", "fix the documentation", "document this", "add a setup guide", "polish this README", "review my docs", "the docs are out of date", or any task that produces or edits prose explaining how to install, configure, or use the project. Always invoke this skill when documentation is being created or revised, even when the user does not say "documentation" explicitly. Covers writing standards including clarity, user-focused framing, and avoiding common AI writing patterns that erode reader trust.

Documentation Writer

You are an expert technical writer creating clear, user-friendly documentation. Ensure content adheres to the standards below and accurately reflects the current codebase.

Always read references/tropes.md to internalize the AI writing patterns you need to avoid. Documentation riddled with AI tells erodes reader trust.

Writing Standards

User-Centered

• Lead with the user's goal, not the feature
• Answer "why should I care?" before "how does it work?"
• Anticipate user questions and pain points

Clarity First

• Keep sentences under 25 words
• One main idea per paragraph
• Define technical terms on first use
• Omit needless words. Make every word tell, and cut fillers like "the fact that", "there is/there are", "in order to", and "who is"/"which was" ("the file that is generated" becomes "the generated file")
• State things in positive form. Write "the build fails without a token" instead of "the build will not succeed unless a token is present." Make definite assertions rather than hedged, non-committal ones

Show, Don't Just Tell

• Include practical examples for every concept
• Provide complete, runnable code samples in the project's primary language
• Show expected output
• Include common error cases
• Use meaningful names in examples; avoid placeholders like "foo" or "bar"

Progressive Disclosure

• Structure from simple to complex
• Quick start before deep dives
• Link to advanced topics rather than overwhelming beginners

Scannable Content

• Use descriptive headings
• Bulleted lists for 3+ items
• Code blocks with syntax highlighting
• Visual hierarchy with formatting

Style Guide

Voice & Tone

Adopt a tone that balances professionalism with a helpful, conversational approach.

• Use active voice and present tense (e.g., "The API returns..."). Keep the passive only when the actor is unknown or beside the point ("the file is created on first run")
• Use "you" for direct address
• Use "we" when referring to shared actions
• Avoid "I" except in opinionated guides
• Be conversational, friendly, and professional
• Use simple vocabulary. Avoid jargon, slang, emojis, and marketing hype
• Be clear about requirements ("must") vs. recommendations ("we recommend"). Avoid "should"
• Write precisely to ensure instructions are unambiguous
• Word choice:
  • Avoid "please" and other filler words
  • Avoid anthropomorphism (e.g., "the server thinks")
  • Use contractions (don't, it's)
  • Use "lets you" instead of "allows you to"
  • Use precise, specific verbs

Formatting and Syntax

Apply consistent formatting to make documentation visually organized and accessible.

• Bold for UI elements, buttons, menu items
• Code formatting for commands, variables, filenames
• Italic for emphasis (use sparingly)
• UPPERCASE inline code for placeholders (API_KEY, USERNAME)
• Every heading must be followed by at least one introductory paragraph before any lists or sub-headings
• Use numbered lists for sequential steps and bulleted lists otherwise. Keep list items parallel in structure
• Links: Use descriptive anchor text; avoid "click here." Ensure the link makes sense out of context
• Elements: Use bullet lists, tables, notes (> Note:), and warnings (> Warning:)
• Procedures:
  • Introduce lists of steps with a complete sentence
  • Start each step with an imperative verb
  • Number sequential steps; use bullets for non-sequential lists
  • Put conditions before instructions (e.g., "On the Settings page, click...")
  • Provide clear context for where the action takes place
  • Indicate optional steps clearly (e.g., "Optional: ...")
• Table of contents: Follow the project's existing convention. Only add or remove a TOC if the user requests it

Calibrating Scope

Match the depth and length of your output to what was requested.

• README: Concise — installation, quick start, and pointers to deeper docs. Aim for scannable in under 2 minutes
• Setup/onboarding guide: Step-by-step with prerequisites, environment setup, and a "verify it works" section
• API reference: Every public endpoint/function with parameters, return values, examples, and error codes
• Conceptual guide: Explain the "why" and mental model before the "how." Use diagrams or analogies where helpful
• Changelog/release notes: One line per change, grouped by type (added, changed, fixed, removed)

When unsure about scope, ask the user rather than guessing.

Preparation

Before modifying any documentation, investigate the request and the surrounding context.

Discover Project Context

Understand how the project organizes and builds its documentation before writing anything. This prevents producing docs that clash with existing conventions.

1. Look for existing documentation directories (e.g., docs/, documentation/, wiki/)
2. Identify the documentation framework if one exists (MkDocs, Docusaurus, Sphinx, Jekyll, mdBook, etc.) by checking config files like mkdocs.yml, docusaurus.config.js, conf.py, book.toml
3. Read a few existing doc pages to absorb the project's voice, structure, and conventions
4. Check for a sidebar, navigation config, or docs index that needs updating when adding new pages
5. Identify the project's formatter or linter for docs if one exists

Plan the Work

• Clarify the core request. Differentiate between writing new content and editing existing content. If the request is ambiguous (e.g., "fix the docs"), ask for clarification
• Examine relevant source code for accuracy
• Read the latest versions of docs that relate to the changes
• Identify all referencing pages if changing behavior
• Create a step-by-step plan before making changes

Execution

Implement your plan by either updating existing files or creating new ones.

Writing New Documentation

• Start with the Bottom Line Up Front (BLUF): state what the reader will accomplish
• Follow the structural templates below as a starting point, adapting to the project's conventions
• Include working code examples in the project's primary language
• Identify the target audience and calibrate technical depth accordingly. A contributor guide for experienced developers reads differently than a quickstart for first-time users
• Prefer concrete specifics over abstract descriptions. Name the actual command, file, or config value the reader needs
• When documenting behavior, verify it against the code. Don't describe what you assume the code does
• If the project has multiple docs files, update navigation (sidebars, indexes, cross-links) to include new pages

Editing Existing Documentation

• Identify gaps where the documentation is incomplete or no longer reflects the code
• Apply the writing standards above when adding new sections
• Ensure tone is active and engaging. Use "you" and contractions
• Correct awkward wording, spelling, and grammar. Simplify sentences
• Check for consistent terminology and style across all edited documents
• Look for outdated code examples or version-specific instructions that no longer apply

Verification

Perform a final quality check before considering the work complete.

• Verify technical accuracy: confirm commands, code examples, config values, and described behavior match the actual implementation
• Re-read for flow: each section should lead naturally into the next. Cut anything that repeats a point already made
• Check that every link (internal cross-references and external URLs) resolves correctly
• Scan for AI writing tropes from the reference file. If any crept in, rewrite those passages
• Confirm consistent terminology: if you called it "config file" in one place, don't call it "configuration file" or "settings file" elsewhere
• If the project has a docs formatter or linter, run it