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 |
When to Use Each Guide
Formatting
Use formatting.md when you need:
- Title and heading structure guidelines
- Paragraph and list formatting rules
- Intro and outro patterns
- SEO-aware keyword placement