| name | docs-writer |
| description | Comprehensive guide for writing high-quality developer documentation. Use this skill when: (1) Creating new documentation pages (tutorials, API references, guides, concepts), (2) Reviewing or improving existing documentation, (3) Establishing documentation standards for a project, (4) Writing READMEs, quickstarts, or getting-started guides, (5) Formatting code examples, callouts, or navigation elements. Applies synthesized best practices from Anthropic Claude, OpenAI Codex, and Google Gemini documentation. |
Documentation Writer
Write developer documentation that is clear, actionable, and developer-centric.
Core Principles
- Code-First: Get developers to working code within the first scroll. Show-don't-tell.
- Progressive Disclosure: Start simple, layer complexity. Don't overwhelm with edge cases upfront.
- Active Voice: Use "you" and imperatives. "Create a file" not "A file should be created."
- Honest Trade-offs: Document limitations alongside features. Developers trust balanced guidance.
- Scannable: Bullets over paragraphs. Tables over prose. Short sentences.
Quick Checklist
Before writing any page:
Page Types
| Type | Purpose | Key Pattern |
|---|
| Tutorial | Hands-on learning | What you'll do → Prerequisites → Steps → Verify → Next |
| API Reference | Parameter lookup | Intro → Parameters table → Response → Errors → Examples |
| Concept/Guide | Deep understanding | Problem → Solution → When to use → Examples → Trade-offs |
| Overview | Navigation hub | Value prop → Feature cards → Get started links |
See references/templates.md for complete templates.
Writing Style
Voice and Tone
- Direct: "Create an interaction" not "You might want to create an interaction"
- Confident: "Use X for Y" not "You could possibly use X for Y"
- Conversational: Write like explaining to a colleague, not a textbook
Sentence Structure
- Lead with purpose: First sentence states what the section covers
- Keep sentences under 25 words
- One idea per paragraph
Technical Terms
- Context first, then name: "To generate responses (using the Interactions API), call..."
- Spell out acronyms on first use: "Model Context Protocol (MCP)"
- Define inline with colons or em-dashes
See references/style-guide.md for detailed guidance.
Formatting Quick Reference
Callouts
| Type | Usage | When to Use |
|---|
<Note> | Contextual info, cross-refs | Methodology notes, scope clarifications |
<Tip> | Best practices, shortcuts | Optimization hints, actionable advice |
<Warning> | Breaking changes, risks | Security issues, destructive actions |
Code Blocks
- Always specify language:
```python, ```bash
- Order: Shell → Python → TypeScript → Java
- Add inline comments for non-obvious lines
- Make code copy-paste ready
Tables
- Left-align text columns
- Use code font for parameter names, types
- Keep cells concise (<15 words)
See references/formatting.md for complete conventions.
Key Patterns
The First Scroll Rule
The first viewport must answer: "What is this and why should I care?"
Tutorial: Show what you'll build + prerequisites
API Reference: Brief description + minimal code example
Concept: Problem statement + solution overview
Example Placement
- Introduce concept (1-2 sentences)
- Show code example
- Explain key parts
Never code without context or explanation.
Before/After Comparisons
Show improvement through examples:
- ❌ Before: "Unclear prompt..."
- ✅ After: "Clear prompt with..."
See references/patterns.md for all patterns.
Common Mistakes
| Mistake | Fix |
|---|
| Wall of text before code | Lead with code example, explain after |
| Vague prerequisites | State exact versions, include links |
| No next steps | End every page with navigation |
| Marketing language | Use technical, precise terms |
| Hiding limitations | Add dedicated "Limitations" section |
Reference Files
Load these based on your task:
- style-guide.md: Detailed voice, tone, sentence patterns
- templates.md: Copy-paste templates for each page type
- formatting.md: Callouts, code blocks, tables, links
- patterns.md: Progressive disclosure, examples, navigation
- components.md: Astro Starlight MDX components (Tabs, Cards, Callouts, Steps, etc.)
