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:
- • Identify page type: Tutorial, API Reference, Concept, or Overview?
- • Define the outcome: What will the reader accomplish after reading?
- • First scroll content: Does the first screen show value (code, clear benefit)?
- • Prerequisites clear: Are requirements explicitly listed?
- • Next steps defined: Where does the reader go after this 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.)