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.)
1---2name: docs-writer3description: 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.4---56# Documentation Writer78Write developer documentation that is clear, actionable, and developer-centric.910## Core Principles11121. **Code-First**: Get developers to working code within the first scroll. Show-don't-tell.132. **Progressive Disclosure**: Start simple, layer complexity. Don't overwhelm with edge cases upfront.143. **Active Voice**: Use "you" and imperatives. "Create a file" not "A file should be created."154. **Honest Trade-offs**: Document limitations alongside features. Developers trust balanced guidance.165. **Scannable**: Bullets over paragraphs. Tables over prose. Short sentences.1718## Quick Checklist1920Before writing any page:2122- [ ] **Identify page type**: Tutorial, API Reference, Concept, or Overview?23- [ ] **Define the outcome**: What will the reader accomplish after reading?24- [ ] **First scroll content**: Does the first screen show value (code, clear benefit)?25- [ ] **Prerequisites clear**: Are requirements explicitly listed?26- [ ] **Next steps defined**: Where does the reader go after this page?2728## Page Types2930| Type | Purpose | Key Pattern |31|------|---------|-------------|32| **Tutorial** | Hands-on learning | What you'll do → Prerequisites → Steps → Verify → Next |33| **API Reference** | Parameter lookup | Intro → Parameters table → Response → Errors → Examples |34| **Concept/Guide** | Deep understanding | Problem → Solution → When to use → Examples → Trade-offs |35| **Overview** | Navigation hub | Value prop → Feature cards → Get started links |3637See [references/templates.md](references/templates.md) for complete templates.3839## Writing Style4041### Voice and Tone4243- **Direct**: "Create an interaction" not "You might want to create an interaction"44- **Confident**: "Use X for Y" not "You could possibly use X for Y"45- **Conversational**: Write like explaining to a colleague, not a textbook4647### Sentence Structure4849- Lead with purpose: First sentence states what the section covers50- Keep sentences under 25 words51- One idea per paragraph5253### Technical Terms5455- Context first, then name: "To generate responses (using the Interactions API), call..."56- Spell out acronyms on first use: "Model Context Protocol (MCP)"57- Define inline with colons or em-dashes5859See [references/style-guide.md](references/style-guide.md) for detailed guidance.6061## Formatting Quick Reference6263### Callouts6465| Type | Usage | When to Use |66|------|-------|-------------|67| `<Note>` | Contextual info, cross-refs | Methodology notes, scope clarifications |68| `<Tip>` | Best practices, shortcuts | Optimization hints, actionable advice |69| `<Warning>` | Breaking changes, risks | Security issues, destructive actions |7071### Code Blocks7273- Always specify language: ` ```python `, ` ```bash `74- Order: Shell → Python → TypeScript → Java75- Add inline comments for non-obvious lines76- Make code copy-paste ready7778### Tables7980- Left-align text columns81- Use code font for parameter names, types82- Keep cells concise (<15 words)8384See [references/formatting.md](references/formatting.md) for complete conventions.8586## Key Patterns8788### The First Scroll Rule8990The first viewport must answer: "What is this and why should I care?"9192**Tutorial**: Show what you'll build + prerequisites 93**API Reference**: Brief description + minimal code example 94**Concept**: Problem statement + solution overview9596### Example Placement97981. Introduce concept (1-2 sentences)992. Show code example1003. Explain key parts101102Never code without context or explanation.103104### Before/After Comparisons105106Show improvement through examples:107- ❌ **Before**: "Unclear prompt..."108- ✅ **After**: "Clear prompt with..."109110See [references/patterns.md](references/patterns.md) for all patterns.111112## Common Mistakes113114| Mistake | Fix |115|---------|-----|116| Wall of text before code | Lead with code example, explain after |117| Vague prerequisites | State exact versions, include links |118| No next steps | End every page with navigation |119| Marketing language | Use technical, precise terms |120| Hiding limitations | Add dedicated "Limitations" section |121122## Reference Files123124Load these based on your task:125126- **[style-guide.md](references/style-guide.md)**: Detailed voice, tone, sentence patterns127- **[templates.md](references/templates.md)**: Copy-paste templates for each page type128- **[formatting.md](references/formatting.md)**: Callouts, code blocks, tables, links129- **[patterns.md](references/patterns.md)**: Progressive disclosure, examples, navigation130- **[components.md](references/components.md)**: Astro Starlight MDX components (Tabs, Cards, Callouts, Steps, etc.)
philschmid