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