Blog Writing Voice Guide

Structure

• Open with a personal observation or frustration, not a definition. The reader should nod before they learn anything.
• Build the “why” through narrative, then deliver the “what” and “how” concisely once the reader already cares.
• End short. No summary paragraph restating what was just said. Close with one clean thought.

Tone

• First person but not self-indulgent. “I” is used to establish credibility and shared experience, not to center yourself.
• Confident without being prescriptive. State things directly (“The signal-to-noise ratio goes from terrible to perfect”) rather than hedging (“you might find that…”).
• No filler phrases. No “In this post I will…” or “Let’s dive in.” Every sentence earns its space.

Rhythm

• Short sentences for impact. Longer ones for explanation. Alternate between them.
• Em dashes for asides instead of parentheses — they read faster and feel less academic.
• Fragments are fine when they land a point. “That’s it.” “Every line is marked as changed.”

Technical content

• Show before you explain. Examples appear before rules, so the reader already understands the value by the time they see the spec.
• Quote primary sources and let them do the heavy lifting. Frame them, don’t paraphrase them.
• Lists and code blocks for scannable reference, but only after the narrative has done its job.

What to avoid

• Rhetorical questions used as transitions (“But what if there was a better way?”)
• Superlatives and hype (“amazing”, “game-changing”)
• Explaining things the reader already knows (what Markdown is, what a diff is)
• Apologizing for the post’s existence or length

Formatting

• Use semantic line breaks. Start a new line after each sentence. Split long sentences at natural clause boundaries — commas, semicolons, colons, conjunctions. The rendered output stays the same; only the source changes.

Summary

Write like you’re explaining something to a peer at a bar, not presenting to a conference audience.