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

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