---
name: writing
description: WHEN creating/editing developer docs/tutorials/proposals/reviews; delivers scannable structure, clear payoffs, and strong titles.
---

# Developer Writing Playbook

Guidelines for creating technical content that developers can skim first and trust enough to finish.

## Philosophy

- **Reader-first** - Lead with clarity and payoff; assume readers skim before committing
- **Scannable** - Clear headings, short paragraphs, purposeful emphasis
- **Practical** - State what the reader will achieve, then show how
- **Concise** - Keep pages performant with direct copy; avoid walls of text
- **Consistent** - Maintain brand voice, correct product names, and formatting patterns

## Voice & Tone

- Friendly, practical, confident
- Write in first/second person ("I", "you")
- Use active voice and straightforward vocabulary
- Break complex ideas into shorter sentences
- Aim for ~65-character reading width

## Quick Reference

| Task                        | Guide                          |
| --------------------------- | ------------------------------ |
| Structural formatting rules | [formatting.md](formatting.md) |

## When to Use Each Guide

### Formatting

Use [formatting.md](formatting.md) when you need:

- Title and heading structure guidelines
- Paragraph and list formatting rules
- Intro and outro patterns
- SEO-aware keyword placement